# vito-mcp

MCP server wrapping the full [VitoDeploy](https://vitodeploy.com) REST API — manage
projects, servers, sites, databases, services, workers, SSL, DNS, and more
through any MCP-compatible agent.

**108 tools** covering every endpoint in the VitoDeploy OpenAPI spec.

## Install

```bash
git clone https://github.com/xerxes-on/vito-mcp.git
cd vito-mcp
uv venv --python 3.11
uv pip install -e .
```

## Configure

Generate a Vito API token in your VitoDeploy panel:
**Settings → API Keys → Create**.

Then register with your MCP client:

### Claude Code

```bash
claude mcp add -s user vito \
  --env VITO_API_TOKEN=<your-token> \
  -- /path/to/vito-mcp/.venv/bin/python -m ufarm_vito.cli
```

To point at a different Vito panel:

```bash
  --env VITO_BASE_URL=https://your-vito.example.com
```

### Codex

```bash
codex mcp add vito \
  --env VITO_API_TOKEN=<your-token> \
  -- /path/to/vito-mcp/.venv/bin/python -m ufarm_vito.cli
```

### Cursor

```json
{
  "mcpServers": {
    "vito": {
      "command": "/path/to/vito-mcp/.venv/bin/python",
      "args": ["-m", "ufarm_vito.cli"],
      "env": {
        "VITO_API_TOKEN": "<your-token>",
        "VITO_BASE_URL": "https://mindep.celion.io"
      }
    }
  }
}
```

### Windsurf / Generic MCP Client

Add to your MCP config:

```json
{
  "mcpServers": {
    "vito": {
      "command": "/path/to/vito-mcp/.venv/bin/python",
      "args": ["-m", "ufarm_vito.cli"],
      "env": {
        "VITO_API_TOKEN": "<your-token>"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `VITO_API_TOKEN` | *(required)* | Sanctum API token from VitoDeploy panel |
| `VITO_BASE_URL` | `https://mindep.celion.io` | VitoDeploy panel URL |
| `VITO_TIMEOUT_SECONDS` | `30` | HTTP request timeout |

## Tools

### Projects & Servers

`list_projects` `create_project` `get_project` `update_project` `delete_project`
`list_servers` `create_server` `get_server` `delete_server` `reboot_server` `upgrade_server`

### Sites & Deployments

`list_sites` `create_site` `get_site` `delete_site`
`deploy_site` `update_site_aliases` `update_web_directory`
`get_deployment_script` `update_deployment_script`
`get_site_env` `update_site_env`
`list_deployments` `create_deployment` `get_deployment`

### Services

`list_services` `get_service` `uninstall_service`
`start_service` `stop_service` `restart_service` `reload_service`
`enable_service` `disable_service`

### Databases

`list_databases` `create_database` `get_database` `delete_database`
`list_database_users` `create_database_user` `get_database_user` `link_database_user` `delete_database_user`

### Workers (Supervisor)

`list_workers` `create_worker` `get_worker` `delete_worker`

### Cron Jobs

`list_cron_jobs` `create_cron_job` `get_cron_job` `delete_cron_job`
`list_site_cron_jobs` `create_site_cron_job` `get_site_cron_job` `delete_site_cron_job`

### Firewall & SSL

`list_firewall_rules` `create_firewall_rule` `get_firewall_rule` `delete_firewall_rule`
`list_ssl_certificates` `create_ssl_certificate` `get_ssl_certificate` `delete_ssl_certificate`

### Workflows

`list_workflows` `get_workflow` `delete_workflow`
`list_workflow_runs` `run_workflow` `get_workflow_run` `get_workflow_run_logs`

### Domains & DNS

`list_domains` `add_domain` `get_domain` `remove_domain` `get_available_domains`
`list_dns_records` `create_dns_record` `get_dns_record` `update_dns_record` `delete_dns_record` `sync_dns_records`
`list_dns_providers` `create_dns_provider` `get_dns_provider` `update_dns_provider` `delete_dns_provider`

### Providers (Server / Storage / Source Control)

`list_server_providers` `create_server_provider` `get_server_provider` `update_server_provider` `delete_server_provider` `get_server_provider_regions` `get_server_provider_plans`
`list_storage_providers` `create_storage_provider` `get_storage_provider` `update_storage_provider` `delete_storage_provider`
`list_source_controls` `create_source_control` `get_source_control` `update_source_control` `delete_source_control`

### Convenience

| Tool | Description |
|---|---|
| `deploy_by_domain(domain)` | Find a site by domain substring and trigger deploy. Case-insensitive: `"calendar.dev"` matches `calendar.dev.example.com`. |
| `find_site_by_domain(domain)` | Same lookup without deploying. Returns project_id, server_id, and site object. |
| `restart_php_fpm_by_site(domain)` | Find site → find PHP services on its server → restart them all. Ideal after deploys. |
| `find_services_by_type(project_id, server_id, type)` | Find services by type (`php`, `nginx`, `redis`, `mysql`, `supervisor`, etc.). |

All tools return `{"ok": true, "data": ...}` on success or `{"ok": false, "status_code": ..., "error": ...}` on failure.

## Quick test (no MCP client)

```bash
VITO_API_TOKEN=<token> uv run python -c "
import asyncio
from ufarm_vito.client import VitoClient
from ufarm_vito.settings import Settings

async def main():
    c = VitoClient(Settings())
    print(await c.list_projects())
    await c.aclose()

asyncio.run(main())
"
```

## License

MIT