# Server Maintenance MCP Server

A Model Context Protocol (MCP) server designed for **Google Antigravity** to securely connect, inspect, and maintain remote Linux/Unix servers over SSH.

---

## Features

- 🖥️ **Configurable Server Registry**: Manage multiple servers with custom IDs, hostnames/IPs, custom ports, usernames, and tags.
- 🔑 **Flexible Authentication**:
  - OpenSSH private keys (`~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, etc.)
  - Passphrase-protected private keys
  - Password authentication
  - Environment variable interpolation (e.g. `"${PROD_PASSWORD}"` or `"${SSH_KEY_SECRET}"`)
- 🛡️ **Credential Protection**:
  - Passwords, passphrases, and private key contents are automatically scrubbed from tool outputs and agent responses.
  - `config/servers.json` is gitignored by default to prevent accidental credential commits.
- ⚡ **Native SSH & SFTP Engine**: Powered by `ssh2` without relying on host `ssh.exe` or terminal emulation quirks on Windows.
- 🧰 **Agent Toolset**:
  - `ssh_list_servers`: View all configured servers and their metadata.
  - `ssh_test_connection`: Test connectivity and measure SSH ping/round-trip latency.
  - `ssh_execute_command`: Run any shell command with working directory, custom timeout, and sudo support.
  - `ssh_system_info`: Inspect real-time CPU model, cores, load averages, memory usage, disk mounts, and uptime.
  - `ssh_read_file`: Read remote files with line offsets and line counts over SFTP.
  - `ssh_write_file`: Upload/edit remote files over SFTP with automatic timestamped backup copies (`.bak-...`).
  - `ssh_list_directory`: Explore remote directories over SFTP with file types, sizes, permissions, and timestamps.
  - `ssh_service_status`: Convenience tool to check, inspect logs, start, stop, or restart systemd services or Docker containers.

---

## Directory Structure

```text
ServerMaintenanceMCP/
├── config/
│   ├── servers.example.json  # Documented configuration template
│   └── servers.json          # Your actual server connections (gitignored)
├── src/
│   ├── config.ts             # Configuration loader & env var expander
│   ├── index.ts              # MCP Stdio Server entrypoint
│   ├── ssh-manager.ts        # SSH & SFTP connection pool and handlers
│   ├── types.ts              # Zod schemas & TypeScript types
│   └── tools/
│       └── index.ts          # Tool schemas and dispatcher
├── test/
│   └── config-and-tools.test.ts # Vitest unit test suite
├── dist/                     # Compiled executable output
├── mcp_config.json           # Antigravity MCP registration template
├── package.json
└── tsconfig.json
```

---

## Quick Start

### 1. Configure Your Servers

Copy `config/servers.example.json` to `config/servers.json`:

```bash
cp config/servers.example.json config/servers.json
```

Edit `config/servers.json` with your actual server details:

```json
{
  "defaultKeyPath": "~/.ssh/id_rsa",
  "servers": [
    {
      "id": "prod-web",
      "name": "Production Web & API Server",
      "host": "192.168.1.50",
      "port": 22,
      "username": "ubuntu",
      "privateKeyPath": "~/.ssh/id_rsa",
      "tags": ["production", "web", "docker"],
      "description": "Nginx reverse proxy and API services",
      "defaultCwd": "/var/www"
    },
    {
      "id": "staging-db",
      "name": "Staging Database Server",
      "host": "staging-db.internal",
      "port": 2222,
      "username": "deploy",
      "password": "${STAGING_DB_PASSWORD}",
      "tags": ["staging", "database"],
      "description": "PostgreSQL staging instance"
    }
  ]
}
```

### 2. Build the Server

```bash
npm run build
```

To run the automated test suite:

```bash
npm test
```

---

## Antigravity Integration

The server has already been registered in your global Antigravity MCP configuration:
`~/.gemini/config/mcp_config.json`

```json
{
  "mcpServers": {
    "server-maintenance": {
      "command": "node",
      "args": [
        "c:/Users/keesj/Documents/repos/ServerMaintenanceMCP/dist/index.js"
      ],
      "env": {
        "SERVERS_CONFIG_PATH": "c:/Users/keesj/Documents/repos/ServerMaintenanceMCP/config/servers.json"
      }
    }
  }
}
```

Once registered, restart Antigravity or refresh MCP tools. You can verify available tools under **Additional Options (...) > MCP Servers**.

---

## Example Antigravity Prompts

Once configured, you can prompt Antigravity directly:

- *"List my configured servers and test connection to each one."*
- *"Check the system health and disk space on `prod-web`."*
- *"Inspect the last 50 lines of the Nginx error log on `prod-web`."*
- *"Check the status of the docker service on `staging-db`."*
- *"Edit `/etc/nginx/sites-available/default` on `prod-web` to update the proxy pass URL and test the configuration with `nginx -t`."*