# Cloud Compute & Storage MCP — Agent Context Document

> **Purpose:** Concise guide for AI agents connecting to this MCP. For the full parameter-level reference, see [MCP_CAPABILITIES.md](MCP_CAPABILITIES.md).

---

## 1. What Is This MCP?

**Cloud Compute & Storage MCP** exposes Serenity Cloud Enterprise cloud infrastructure as **10 workflow-optimised tools** with **85 total actions**. Each tool orchestrates multiple API calls in parallel, validates quota before provisioning, and matches images/flavors by regex pattern.

**Domains:** Compute (VMs, bare metal), Storage (volumes, snapshots), Networking (networks, subnets, routers), IP management (floating + reserved), Load balancing (LBs, listeners, pools, members), Security (groups, SSH keys), Projects, Regions, Quotas.

**When to use:** Requests about cloud, VMs, servers, volumes, disks, networks, subnets, load balancers, deploy, infrastructure, security groups, SSH keys, floating IPs, snapshots, bare metal.

---

## 2. Tools at a Glance

| # | Tool | Actions | Domain |
|---|------|---------|--------|
| 1 | `discover_infrastructure` | 2 | Projects, regions, quotas |
| 2 | `provision_vm` | — | Quota-aware VM creation with regex image/flavor matching |
| 3 | `provision_baremetal` | — | Quota-aware bare metal creation |
| 4 | `provision_load_balancer` | — | LB creation with quota pre-check |
| 5 | `manage_compute` | 17 | VM lifecycle, resize, interfaces, catalog |
| 6 | `manage_storage` | 11 | Volumes, snapshots, attach/detach/extend |
| 7 | `manage_networking` | 16 | Networks, subnets, routers |
| 8 | `manage_ips` | 12 | Floating IPs, reserved fixed IPs |
| 9 | `manage_security` | 10 | Security groups, SSH keys |
| 10 | `manage_load_balancers` | 14 | LB lifecycle, listeners, pools, members |

---

## 3. Action Quick-Reference

### `manage_compute` (17 actions)
`list_vms` `get_vm` `start_vm` `stop_vm` `delete_vm` `resize_vm` `update_vm` `list_interfaces` `attach_interface` `detach_interface` `list_baremetal` `rebuild_baremetal` `list_images` `list_vm_flavors` `list_baremetal_images` `list_baremetal_flavors` `list_lb_flavors`

### `manage_storage` (11 actions)
`list_volumes` `get_volume` `create_volume` `delete_volume` `extend_volume` `create_snapshot` `get_snapshot` `update_snapshot` `delete_snapshot` `attach_volume` `detach_volume`

### `manage_networking` (16 actions)
`list_networks` `get_network` `create_network` `update_network` `delete_network` `list_subnets` `get_subnet` `create_subnet` `delete_subnet` `list_routers` `get_router` `create_router` `update_router` `delete_router` `attach_subnet` `detach_subnet`

### `manage_ips` (12 actions)
`list_floating_ips` `get_floating_ip` `create_floating_ip` `assign_floating_ip` `unassign_floating_ip` `delete_floating_ip` `list_reserved_ips` `get_reserved_ip` `create_reserved_ip_external` `create_reserved_ip_subnet` `update_reserved_ip` `delete_reserved_ip`

### `manage_security` (10 actions)
`list_security_groups` `get_security_group` `create_security_group` `update_security_group` `delete_security_group` `list_ssh_keys` `get_ssh_key` `create_ssh_key` `update_ssh_key` `delete_ssh_key`

### `manage_load_balancers` (14 actions)
`list` `get` `update` `delete` `list_listeners` `create_listener` `get_listener` `delete_listener` `list_pools` `create_pool` `get_pool` `delete_pool` `add_member` `delete_member`

---

## 4. Workflow Recipes

### A. Full-Stack Deploy (VM + storage + LB + network + security)

```
1. discover_infrastructure(include_quotas=True, client_id=N)
2. manage_security(action="create_ssh_key", name="deploy-key", public_key="ssh-rsa ...")
3. manage_security(action="create_security_group", name="web-sg", rules=[
     {"direction":"ingress","protocol":"tcp","port_range_min":22,"port_range_max":22},
     {"direction":"ingress","protocol":"tcp","port_range_min":80,"port_range_max":80},
     {"direction":"ingress","protocol":"tcp","port_range_min":443,"port_range_max":443}
   ])
4. manage_networking(action="create_network", name="app-net", create_router_flag=True)
5. manage_networking(action="create_subnet", name="app-sub", network_id="...", cidr="10.0.1.0/24")
6. provision_vm(name="web-1", image_pattern="ubuntu.*24", flavor_pattern="standard-2-4",
     user_data="<base64>", client_id=N)
7. manage_storage(action="create_volume", name="data-vol", size=100, source="new-volume")
8. manage_storage(action="attach_volume", volume_id="...", instance_id="...")
9. provision_load_balancer(name="web-lb", client_id=N, listeners=[
     {"name":"http","protocol":"HTTP","protocol_port":80,
      "pools":[{"name":"web-pool","lb_algorithm":"ROUND_ROBIN","protocol":"HTTP",
        "members":[{"address":"10.0.1.x","protocol_port":8080,"instance_id":"..."}]}]}
   ])
```

### B. Microservices (multiple VMs behind LB with pool routing)

```
1. discover_infrastructure(include_quotas=True, client_id=N)
2. manage_networking(action="create_network", name="micro-net")
3. manage_networking(action="create_subnet", name="micro-sub", network_id="...", cidr="10.0.2.0/24")
4. provision_vm(name="svc-api", image_pattern="ubuntu.*24", flavor_pattern="standard-2")
5. provision_vm(name="svc-worker", image_pattern="ubuntu.*24", flavor_pattern="standard-4")
6. provision_vm(name="svc-db", image_pattern="ubuntu.*24", flavor_pattern="standard-4-16",
     boot_disk_gb=50, volume_ids=["<pre-created-vol>"])
7. provision_load_balancer(name="micro-lb", client_id=N)
8. manage_load_balancers(action="create_listener", load_balancer_id="...",
     name="api", protocol="HTTP", protocol_port=80)
9. manage_load_balancers(action="create_pool", name="api-pool",
     lb_algorithm="ROUND_ROBIN", protocol="HTTP", listener_id="...")
10. manage_load_balancers(action="add_member", pool_id="...",
      address="10.0.2.x", protocol_port=8080, instance_id="...")
```

### C. Create a VM (1-2 calls)

```
provision_vm(name="web1", image_pattern="ubuntu.*24", flavor_pattern="standard-2", client_id=N)
```
Auto-selects best region with quota. Or specify `region_id` directly.

### D. Attach/Extend Storage

```
manage_storage(action="create_volume", name="data", size=200, source="new-volume")
manage_storage(action="attach_volume", volume_id="...", instance_id="...")
manage_storage(action="extend_volume", volume_id="...", size=500)
```

### E. Snapshot a Volume

```
manage_storage(action="create_snapshot", name="pre-upgrade", volume_id="...")
manage_storage(action="get_snapshot", snapshot_id="...")
```

### F. Add Network Interface to Running VM

```
manage_networking(action="create_network", name="backend-net")
manage_networking(action="create_subnet", name="backend-sub", network_id="...", cidr="10.0.3.0/24")
manage_compute(action="attach_interface", instance_id="...",
  network_type="subnet", network_id="...", subnet_id="...")
```

### G. Resize a VM

```
manage_compute(action="stop_vm", instance_id="...")
manage_compute(action="resize_vm", instance_id="...", flavor_id="g1-standard-4-8")
manage_compute(action="start_vm", instance_id="...")
```

### H. Scale LB Backend

```
manage_load_balancers(action="list_pools", load_balancer_id="...")
manage_load_balancers(action="add_member", pool_id="...",
  address="192.168.1.50", protocol_port=8080, instance_id="...")
```

### I. Complete Teardown

```
1. manage_load_balancers(action="list")       → delete each LB
2. manage_compute(action="list_vms")          → stop + delete each VM
3. manage_storage(action="list_volumes")      → detach + delete each volume
4. manage_networking(action="list_networks")  → delete subnets, then networks
```

### J. Browse Catalog

| Goal | Call |
|------|------|
| VM images | `manage_compute(action="list_images")` |
| VM flavors + pricing | `manage_compute(action="list_vm_flavors", include_prices=True)` |
| Bare metal images | `manage_compute(action="list_baremetal_images")` |
| Bare metal flavors | `manage_compute(action="list_baremetal_flavors")` |
| LB flavors | `manage_compute(action="list_lb_flavors")` |

---

## 5. Key Parameter Values

| Parameter | Valid Values |
|-----------|-------------|
| Volume `source` | `"new-volume"` (blank), `"image"`, `"snapshot"` |
| Volume `type_name` | `"standard"`, `"ssd_hiiops"`, `"ssd_lowlatency"`, `"cold"`, `"ultra"` |
| Network `type` | `"external"`, `"subnet"`, `"any_subnet"`, `"reserved_fixed_ip"` |
| LB algorithm | `"ROUND_ROBIN"`, `"LEAST_CONNECTIONS"`, `"SOURCE_IP"` |
| LB protocol | `"HTTP"`, `"HTTPS"`, `"TCP"`, `"UDP"`, `"TERMINATED_HTTPS"` |

---

## 6. Safety Rules

1. **Read before write:** Use list/get actions before mutations.
2. **Stop before resize/delete:** VMs must be stopped before `resize_vm` or `delete_vm`.
3. **Detach before delete:** Volumes must be detached before `delete_volume`.
4. **Quota awareness:** Pass `client_id` to provisioning tools when available.
5. **Explain changes:** Describe planned mutations before executing.

---

## 7. User Intent → Tool

| User says… | Tool call |
|------------|-----------|
| "What regions are available?" | `discover_infrastructure` |
| "Which regions have capacity?" | `discover_infrastructure(include_quotas=True, client_id=N)` |
| "Create a VM" | `provision_vm(...)` |
| "Create a bare metal server" | `provision_baremetal(...)` |
| "Set up a load balancer" | `provision_load_balancer(...)` |
| "List my VMs" | `manage_compute(action="list_vms")` |
| "Stop/start that VM" | `manage_compute(action="stop_vm/start_vm", ...)` |
| "Resize my VM" | `manage_compute(action="resize_vm", ...)` |
| "Add a network to my VM" | `manage_compute(action="attach_interface", ...)` |
| "Create a volume / disk" | `manage_storage(action="create_volume", ...)` |
| "Attach disk to VM" | `manage_storage(action="attach_volume", ...)` |
| "Make volume bigger" | `manage_storage(action="extend_volume", ...)` |
| "Snapshot my volume" | `manage_storage(action="create_snapshot", ...)` |
| "Create a private network" | `manage_networking(action="create_network", ...)` |
| "Add a subnet" | `manage_networking(action="create_subnet", ...)` |
| "Show me images / flavors" | `manage_compute(action="list_images/list_vm_flavors")` |
| "Get a floating IP" | `manage_ips(action="create_floating_ip")` |
| "Create firewall rules" | `manage_security(action="create_security_group", ...)` |
| "Add an SSH key" | `manage_security(action="create_ssh_key", ...)` |
| "Add backend to my LB" | `manage_load_balancers(action="add_member", ...)` |
| "Create an HTTP listener" | `manage_load_balancers(action="create_listener", ...)` |
| "Deploy microservices" | Workflow B |
| "Deploy full stack" | Workflow A |
| "Delete everything" | Workflow I |