WI: Implement anima-qa MCP server (HTTP + JSON-RPC) #181

New issue

Closed

opened 2026-05-24 05:10:18 +00:00 by toasterson · 0 comments

toasterson commented

2026-05-24 05:10:18 +00:00

Owner

Goal

Implement the anima-qa MCP server with full tool registration and VM lifecycle management.

Background

This is the core server that receives test instructions from OpenClaw agents and translates them into vm-manager operations. Communicates via MCP HTTP protocol (JSON-RPC 2.0).

🔗 Remote Sources (all on code.aopc.cloud)

vm-manager — VM lifecycle management library:

Repo: https://code.aopc.cloud/CloudNebulaProject/vm-manager (mirror from GitHub)
Clone: git clone https://code.aopc.cloud/CloudNebulaProject/vm-manager.git
Key source files (browse online):
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/traits.rs — Hypervisor trait: prepare(), start(), stop(timeout), destroy(), suspend(), resume(), state(), guest_ip(), console_endpoint()
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/types.rs — VmSpec, VmHandle, VmState, NetworkConfig, CloudInitConfig, SshConfig
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/qemu.rs — QemuBackend::new(qemu_binary, data_dir, default_bridge) — KVM-backed, all async
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/qmp.rs — QMP client for graceful shutdown via Unix socket
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/mod.rs — RouterHypervisor with platform-aware backend dispatch
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/image.rs — ImageManager::new() downloads images, create_overlay(base, overlay, size_gb) creates QCOW2 snapshots
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/console.rs — ConsoleTailer::tail(endpoint, line_tx, stop_rx) streams serial console lines
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/cloudinit.rs — create_nocloud_iso_raw() generates cloud-init seed ISOs
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/ssh.rs — SSH key generation and management
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/vmfile.rs — VMFile.kdl parser (declarative VM specs)
- https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/VMFile.kdl — example VM spec using KDL format

Anima workspace:

Repo: https://code.aopc.cloud/toasterson/Anima
Clone: git clone https://code.aopc.cloud/toasterson/Anima.git
https://code.aopc.cloud/toasterson/Anima/src/branch/main/Cargo.toml — workspace deps include tokio, axum 0.8, serde_json, tracing, base64, reqwest
Add to workspace members: "crates/anima-qa"

Design doc: Ask Tecton for memory/projects/anima-qa.md — full architecture spec

🏗️ Implementation Guide

Step 1: Add crate to workspace

Add "crates/anima-qa" to the members array in root Cargo.toml.

Cargo.toml for anima-qa:

[package]
name = "anima-qa"
version.workspace = true
edition.workspace = true
license.workspace = true

[dependencies]
tokio.workspace = true
axum.workspace = true
serde = { workspace = true, features = ["derive"] }
serde_json.workspace = true
tracing.workspace = true
base64.workspace = true
reqwest.workspace = true
uuid.workspace = true
ssh2 = "0.9"
openssl = { version = "0.10", features = ["vendored"] }
vm-manager = { git = "https://code.aopc.cloud/CloudNebulaProject/vm-manager.git" }

Step 2: MCP protocol handler

Implement JSON-RPC 2.0 request parsing. 10 tools each with JSON Schema parameter definitions. Error codes: -32700 (parse), -32601 (method not found), -32603 (internal).

Step 3: Action handlers

QaMcpServer struct holds RouterHypervisor, ImageManager, active VM registry.
VM spec for QA: name "qa-{uuid}", image from cache dir, 4 vCPUs, 4GB RAM, 20GB disk, User networking, cloud-init for qa user, SSH, UEFI.

Step 4: HTTP server

axum Router with POST /mcp and GET /health. Bind to 0.0.0.0:8090 (override with QA_MCP_PORT env).

✅ Acceptance Criteria

Builds and runs
tools/list returns 10 tools
VM lifecycle: boot → execute → destroy
Concurrent VMs supported

#180 — crate skeleton (prerequisite)
#182 — CLI runner
#184 — visual testing

## Goal Implement the anima-qa MCP server with full tool registration and VM lifecycle management. ## Background This is the core server that receives test instructions from OpenClaw agents and translates them into vm-manager operations. Communicates via MCP HTTP protocol (JSON-RPC 2.0). ## 🔗 Remote Sources (all on code.aopc.cloud) **vm-manager** — VM lifecycle management library: - **Repo:** https://code.aopc.cloud/CloudNebulaProject/vm-manager (mirror from GitHub) - **Clone:** `git clone https://code.aopc.cloud/CloudNebulaProject/vm-manager.git` - **Key source files (browse online):** - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/traits.rs — `Hypervisor` trait: `prepare()`, `start()`, `stop(timeout)`, `destroy()`, `suspend()`, `resume()`, `state()`, `guest_ip()`, `console_endpoint()` - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/types.rs — `VmSpec`, `VmHandle`, `VmState`, `NetworkConfig`, `CloudInitConfig`, `SshConfig` - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/qemu.rs — `QemuBackend::new(qemu_binary, data_dir, default_bridge)` — KVM-backed, all async - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/qmp.rs — QMP client for graceful shutdown via Unix socket - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/backends/mod.rs — `RouterHypervisor` with platform-aware backend dispatch - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/image.rs — `ImageManager::new()` downloads images, `create_overlay(base, overlay, size_gb)` creates QCOW2 snapshots - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/console.rs — `ConsoleTailer::tail(endpoint, line_tx, stop_rx)` streams serial console lines - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/cloudinit.rs — `create_nocloud_iso_raw()` generates cloud-init seed ISOs - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/ssh.rs — SSH key generation and management - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/crates/vm-manager/src/vmfile.rs — VMFile.kdl parser (declarative VM specs) - https://code.aopc.cloud/CloudNebulaProject/vm-manager/src/branch/main/VMFile.kdl — example VM spec using KDL format **Anima workspace:** - **Repo:** https://code.aopc.cloud/toasterson/Anima - **Clone:** `git clone https://code.aopc.cloud/toasterson/Anima.git` - https://code.aopc.cloud/toasterson/Anima/src/branch/main/Cargo.toml — workspace deps include tokio, axum 0.8, serde_json, tracing, base64, reqwest - Add to workspace members: `"crates/anima-qa"` **Design doc:** Ask Tecton for `memory/projects/anima-qa.md` — full architecture spec ## 🏗️ Implementation Guide ### Step 1: Add crate to workspace Add `"crates/anima-qa"` to the `members` array in root Cargo.toml. Cargo.toml for anima-qa: ```toml [package] name = "anima-qa" version.workspace = true edition.workspace = true license.workspace = true [dependencies] tokio.workspace = true axum.workspace = true serde = { workspace = true, features = ["derive"] } serde_json.workspace = true tracing.workspace = true base64.workspace = true reqwest.workspace = true uuid.workspace = true ssh2 = "0.9" openssl = { version = "0.10", features = ["vendored"] } vm-manager = { git = "https://code.aopc.cloud/CloudNebulaProject/vm-manager.git" } ``` ### Step 2: MCP protocol handler Implement JSON-RPC 2.0 request parsing. 10 tools each with JSON Schema parameter definitions. Error codes: -32700 (parse), -32601 (method not found), -32603 (internal). ### Step 3: Action handlers QaMcpServer struct holds RouterHypervisor, ImageManager, active VM registry. VM spec for QA: name "qa-{uuid}", image from cache dir, 4 vCPUs, 4GB RAM, 20GB disk, User networking, cloud-init for qa user, SSH, UEFI. ### Step 4: HTTP server axum Router with POST /mcp and GET /health. Bind to 0.0.0.0:8090 (override with QA_MCP_PORT env). ## ✅ Acceptance Criteria - [ ] Builds and runs - [ ] tools/list returns 10 tools - [ ] VM lifecycle: boot → execute → destroy - [ ] Concurrent VMs supported ## Related WIs - #180 — crate skeleton (prerequisite) - #182 — CLI runner - #184 — visual testing

toasterson referenced this issue

2026-05-24 05:22:18 +00:00

WI: Build QA runner CLI for CI integration #182

toasterson referenced this issue

2026-05-24 05:22:18 +00:00

WI: Implement visual testing primitives (screenshot + assertion + input injection) #184

toasterson referenced this issue

2026-05-24 05:22:19 +00:00

WI: Implement YAML test spec parser and executor #185

toasterson referenced this issue

2026-05-24 05:30:28 +00:00

WI: Create anima-qa crate in Anima workspace #180