# meshpop (mpop)

All-in-one server management CLI for VPN mesh networks. Monitor, manage, and automate multi-server infrastructure from a single command.

## Quick Start

```bash
pip install meshpop
```

This installs both `mpop` CLI and `mpop-mcp` MCP server.

## MCP Server Setup

Add to Claude Code config (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "mpop": { "command": "mpop-mcp" }
  }
}
```

If `mpop-mcp` is not on PATH:

```json
{
  "mcpServers": {
    "mpop": { "command": "python3", "args": ["-m", "mpop_mcp_server"] }
  }
}
```

## MCP Tools Reference

### Overview & Monitoring

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_dashboard` | — | Main dashboard overview |
| `mpop_servers` | — | List all servers with names, IPs, roles |
| `mpop_info` | `server`, `raw` | Deep server details — GPU, processes, security, agent |
| `mpop_full` | — | Comprehensive 9-table report with AI summary |
| `mpop_hw` | — | Local hardware info — CPU, GPU, RAM, disk, NIC |
| `mpop_temp` | — | CPU/GPU temperatures across servers |
| `mpop_gpu` | — | GPU status — VRAM, utilization, processes |
| `mpop_services` | — | Running services on each server |
| `mpop_logs` | `server` (required), `type` (required) | View server logs (auth, nginx, system) |
| `mpop_watch` | `interval`, `alert` | Real-time monitoring with anomaly alerts |
| `mpop_trend` | `hours`, `server` | Historical trends — memory, disk, uptime |
| `mpop_matrix` | — | Server-to-server connectivity matrix |
| `mpop_diff` | `server1`, `server2` (required) | Compare two servers side-by-side |

### Security

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_security` | — | Security overview — firewall, fail2ban, ports, SSH |
| `mpop_audit` | `server` | Detailed security audit |
| `mpop_ssh_attacks` | — | SSH attack analysis — patterns, top IPs, geo distribution |

### Network & VPN

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_vpn` | — | VPN status (Wire + Tailscale) |
| `mpop_peers` | — | Connected VPN peers and IPs |
| `mpop_watchdog` | `action` (required), `server` | VPN watchdog daemon — auto-restart on disconnect |

### Execution

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_exec` | `command` (required), `server`, `shell` | Run shell command on any server |
| `mpop_python` | `code` (required), `server`, `python` | Run Python code on local or remote server |
| `mpop_raw` | `command` (required) | Run raw mpop CLI command with pipes/redirects |
| `mpop_delete` | `server`, `path` (required) | Safe file deletion (system paths blocked) |

### File Operations

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_read_file` | `path` (required), `server`, `lines` | Read file (local or remote via SSH) |
| `mpop_write_file` | `path`, `content` (required), `append`, `executable` | Write to local file |
| `mpop_chunk_write` | `path`, `chunk`, `mode` (required) | Write large files in chunks |
| `mpop_scp` | `local_path`, `server` (required), `remote_path`, `direction` | SCP file transfer |

### NAS

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_nas_ls` | `path`, `recursive`, `pattern` | List NAS files |
| `mpop_nas_read` | `path` (required), `lines`, `tail` | Read NAS file |
| `mpop_nas_write` | `path`, `content` (required), `append` | Write to NAS |
| `mpop_nas_backup` | `server`, `source` (required), `dest` | Backup server data to NAS |
| `mpop_nas_usage` | `path` | NAS disk usage and storage summary |

### AI & Diagnostics

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_ai` | `hours` | AI trend analysis — predicts status changes |
| `mpop_heal` | `server`, `execute` | Auto-detect problems and suggest/apply fixes |
| `mpop_predict` | `server` | Predict future issues (disk full, memory pressure) |
| `mpop_advise` | `category`, `target`, `ai` | Infrastructure upgrade/optimization advisor |
| `mpop_logai` | `node`, `errors_only` | AI-powered cross-server log analysis |
| `mpop_ask` | `query` (required), `execute` | Natural language → mpop commands |

### Config & Deploy

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_config` | `action`, `key`, `value` | View/modify mpop configuration |
| `mpop_setup` | `server` (required), `component`, `execute` | Install mpop/vssh/agent on remote servers |
| `mpop_deploy` | `target` (required), `servers` | Deploy files or binary to servers |
| `mpop_backup` | `action`, `server` | Backup server configurations |
| `mpop_secret` | `action`, `key` | Encrypted secret/credential management |

### Agents & Automation

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_agent_list` | — | List custom automation agents |
| `mpop_agent_make` | `name`, `description`, `behavior` (required) | Create agent from description |
| `mpop_agent_deploy` | `name` (required), `servers` | Deploy agent to servers |
| `mpop_agent_run` | `name` (required), `server` | Run an agent |
| `mpop_agent_workflow` | `action`, `name`, `agents` (required) | Multi-agent sequential workflows |
| `mpop_agent_chain` | `action`, `name`, `agents` (required) | Pipe agent outputs via JSON |

### Knowledge & Integration

| Tool | Parameters | Description |
|------|-----------|-------------|
| `mpop_brain` | `action`, `keyword` | Search indexed knowledge base |
| `mpop_project` | `name`, `action` | Project management — status, history |
| `mpop_memory` | `action`, `path`, `project`, `question` | Code knowledge base + Q&A |
| `mpop_rag` | `action`, `path`, `query`, `server`, `type`, `embed`, `replace` | Document Q&A with RAG |
| `mpop_notify` | `platform`, `message` (required) | Send via Slack/Discord/Telegram/Email |
| `mpop_webhook` | `action`, `name`, `command` | Webhook management |
| `mpop_workflow` | `action`, `name` | Predefined workflows (health, security, deploy) |
| `mpop_export` | `filename` | Generate shareable HTML status report |

## CLI Usage

```bash
mpop status                    # Dashboard
mpop servers                   # List all servers
mpop exec v1 "df -h"          # Run command on v1
mpop logs v1 auth              # View auth logs
mpop security                  # Security overview
mpop heal v1                   # Auto-detect and fix issues
mpop ask "which server is low on disk?" # Natural language query
mpop enforce                    # Cold automated enforcement scan
```

## Requirements

- Python 3.8+
- pyyaml, requests
- Servers accessible via SSH (Wire VPN or Tailscale)

## License

MIT — [MeshPOP](https://github.com/meshpop)
