# Sympathy-MCP

MCP server for Incus VM operations. Named for sympathetic magic — the connection between puppet and puppeteer.

Agents on masternode puppeteer VMs via structured MCP tools instead of freeform Bash commands.

## Tools

| Tool | Description |
|------|-------------|
| `vm_exec` | Run a command inside a VM (stdout, stderr, exit code) |
| `vm_file_read` | Read a file from inside a VM |
| `vm_file_write` | Write content to a file inside a VM |
| `vm_file_push` | Push a file from host into a VM |
| `vm_file_pull` | Pull a file from a VM to host |
| `vm_snapshot` | Create a named snapshot |
| `vm_restore` | Restore to a named snapshot |
| `vm_status` | Get VM state, IP, resource usage |
| `vm_list` | List all VMs with status |

## Usage

```bash
# Run the MCP server (stdio transport)
uv run python -m sympathy_mcp

# Or via entry point
uv run sympathy-mcp
```

## MCP Configuration

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "sympathy-mcp": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/Sympathy-MCP", "sympathy-mcp"]
    }
  }
}
```

## Requirements

- Python 3.12+
- `incus` CLI installed and configured
- `uv` for project management

## Architecture

- `src/sympathy_mcp/incus.py` — Async Incus CLI wrapper (validation, subprocess exec, structured results)
- `src/sympathy_mcp/server.py` — FastMCP server with 9 tools (stdio transport)

Shells out to `incus` CLI under the hood. Go rewrite planned.