Feat/agent mode and mcp (#14)

* feat(cli): add --agent mode and MCP server for AI agent integration

Add two features for AI agent integration with Verda CLI:

**--agent mode:**
- Global `--agent` flag (and `VERDA_AGENT=1` env var) that forces JSON
  output, disables interactive prompts, and returns structured errors
- AgentError type with JSON serialization and semantic exit codes
- Agent prompter that returns structured errors instead of blocking
- vm create: returns MISSING_REQUIRED_FLAGS error instead of wizard
- vm action: adds --action and --yes flags for non-interactive use

**MCP server (`verda mcp serve`):**
- Model Context Protocol server over stdio for Claude Code, Cursor, etc.
- 15 tools: discovery (locations, instance types, images, availability),
  cost (balance, estimate, running), VM lifecycle (create, list, describe,
  action), SSH (keys, ssh command), volumes (list, create, trash)
- Uses Verda Go SDK directly, reuses CLI credential resolution
- Configured via standard MCP client settings

* feat(cli): standardize agent error classification with design doc

Add ClassifyError() that maps all errors to structured AgentError types
in --agent mode. Errors are classified by priority:

1. Already an AgentError (from explicit command checks)
2. SDK APIError → mapped by HTTP status (401→AUTH, 404→NOT_FOUND, 402→INSUFFICIENT_BALANCE)
3. SDK ValidationError → VALIDATION_ERROR with field/reason
4. Auth-related message heuristic → AUTH_ERROR
5. Fallback → generic ERROR

This ensures agents always receive JSON errors on stderr, never plain text.

Also adds docs/agent-errors.md with the complete error format specification
for developers and AI agents.


* fix(mcp): skip credential resolution at startup for instant handshake

PersistentPreRunE runs opts.Complete() for every command, which
resolves credentials from ~/.verda/credentials and can be slow
(network calls for token exchange). This caused MCP clients like
Cursor to time out during the handshake.

Now mcp serve skips opts.Complete() at startup and defers credential
resolution to the lazy client func called on first tool invocation.
The handshake completes in ~0.3s instead of 14+s.

Author: hi-lei

.gitignore

@@ -3,6 +3,10 @@ bin/
 _output/
 verda
 
+# Git worktrees
+.worktrees/
+
+
 # Local smoke-test output (see test/run.sh)
 tmp/
 
@@ -240,6 +244,8 @@ cscope.po.out
 
 # Other names that would make sense
 *tests
+!tests/
+!tests/**
 *testsdir
 *testsfile
 *testsfiles

Makefile

@@ -1,6 +1,6 @@
 OUTPUT_DIR ?= bin
 
-.PHONY: all build clean lint lint.fix test fmt changelog hooks.install pre-commit help
+.PHONY: all build clean lint lint.fix test test.integration fmt changelog hooks.install pre-commit help
 
 ## Build -------------------------------------------------------------------
 
@@ -25,6 +25,10 @@ lint.fix: ## Run golangci-lint with auto-fix
 test: ## Run all tests
 	@go test -count=1 ./...
 
+test.integration: build ## Run integration tests (requires staging credentials in [test] profile)
+	@cp $(OUTPUT_DIR)/verda /usr/local/bin/verda-test
+	@VERDA_BIN=$(CURDIR)/$(OUTPUT_DIR)/verda go test -tags=integration -v -count=1 -timeout=5m ./tests/integration/
+
 fmt: ## Format code with gofmt and goimports
 	@gofmt -w .
 	@goimports -w -local github/verda-cloud/verda-cli .

README.md

@@ -2,6 +2,10 @@
 
 Command-line interface for [Verda Cloud](https://verda.com) — manage VMs, volumes, SSH keys, startup scripts, and more from your terminal.
 
+![verda vm create](docs/images/vm-create-demo.gif)
+
+Both interactive and non-interactive modes — use the wizard for quick tasks, flags for scripts and automation.
+
 ## Install
 
 ### Quick install (macOS / Linux)
@@ -16,56 +20,36 @@ Install to a custom directory:
 VERDA_INSTALL_DIR=~/.local/bin curl -sSL https://raw.githubusercontent.com/verda-cloud/verda-cli/main/scripts/install.sh | sh
 ```
 
-Install a specific version:
-
-```bash
-VERDA_VERSION=v1.0.0 curl -sSL https://raw.githubusercontent.com/verda-cloud/verda-cli/main/scripts/install.sh | sh
-```
-
 ### Manual download
 
 Download the binary for your platform from [GitHub Releases](https://github.com/verda-cloud/verda-cli/releases):
 
-
-| Platform              | File                                |
-| --------------------- | ----------------------------------- |
+| Platform | File |
+|----------|------|
 | macOS (Apple Silicon) | `verda_VERSION_darwin_arm64.tar.gz` |
-| macOS (Intel)         | `verda_VERSION_darwin_amd64.tar.gz` |
-| Linux (x86_64)        | `verda_VERSION_linux_amd64.tar.gz`  |
-| Linux (ARM64)         | `verda_VERSION_linux_arm64.tar.gz`  |
-| Windows (x86_64)      | `verda_VERSION_windows_amd64.zip`   |
-| Windows (ARM64)       | `verda_VERSION_windows_arm64.zip`   |
-
-
-Extract and move to your PATH:
+| macOS (Intel) | `verda_VERSION_darwin_amd64.tar.gz` |
+| Linux (x86_64) | `verda_VERSION_linux_amd64.tar.gz` |
+| Linux (ARM64) | `verda_VERSION_linux_arm64.tar.gz` |
+| Windows (x86_64) | `verda_VERSION_windows_amd64.zip` |
+| Windows (ARM64) | `verda_VERSION_windows_arm64.zip` |
 
 ```bash
 tar xzf verda_*.tar.gz
 sudo mv verda /usr/local/bin/
 ```
 
-### Go install (for Go developers)
+### Go install
 
 ```bash
 go install github.com/verda-cloud/verda-cli/cmd/verda@latest
 ```
 
-### Verify installation
-
-```bash
-verda version
-```
-
-### Update to latest version
-
-```bash
-verda update
-```
-
-Or install a specific version:
+### Verify & update
 
 ```bash
-verda update --version v1.0.0
+verda version            # verify installation
+verda update             # update to latest
+verda update --version v1.0.0  # specific version
 ```
 
 ## Getting Started
@@ -76,17 +60,15 @@ verda update --version v1.0.0
 verda auth login
 ```
 
-This starts an interactive wizard to save your API credentials to `~/.verda/credentials`.
-
-### 2. List your VMs
+### 2. Explore available resources
 
 ```bash
-verda vm list
+verda locations                        # datacenter locations
+verda instance-types --gpu             # GPU instance types with pricing
+verda availability --location FIN-01   # what's in stock
 ```
 
-### 3. Create a VM
-
-![verda vm create](docs/images/vm-create-demo.gif)
+### 3. Deploy a VM
 
 ```bash
 # Interactive wizard
@@ -102,202 +84,66 @@ verda vm create \
   --hostname gpu-runner
 ```
 
-## Commands
-
-```
-Auth Commands:
-  auth              Manage shared credentials and profiles
-
-VM Commands:
-  vm                Manage VM instances
-  ssh               SSH into a running VM instance
-
-Resource Commands:
-  availability      Check instance type availability
-  images            List available OS images
-  instance-types    List instance types with specs and pricing
-  locations         List datacenter locations
-  ssh-key           Manage SSH keys
-  startup-script    Manage startup scripts
-  volume            Manage volumes
-
-Info Commands:
-  cost              Cost estimation, pricing, and billing
-
-Other Commands:
-  completion        Generate shell completion scripts
-  settings          Manage CLI settings
-  update            Update Verda CLI to latest or specific version
-  version           Print version information
-```
-
-### VM
-
-
-| Command              | Description                                |
-| -------------------- | ------------------------------------------ |
-| `verda vm create`    | Create a VM (interactive wizard or flags)  |
-| `verda vm list`      | List and inspect VM instances              |
-| `verda vm describe`  | Show detailed info about a single VM       |
-| `verda vm action`    | Start, shutdown, hibernate, or delete a VM |
-
-
-### SSH
+### 4. Connect
 
 ```bash
-# Connect by hostname
 verda ssh gpu-runner
-
-# Connect with options
-verda ssh gpu-runner --user ubuntu --key ~/.ssh/id_ed25519
-
-# Port forwarding and other ssh args
-verda ssh gpu-runner -- -L 8080:localhost:8080
-```
-
-### Volume
-
-
-| Command                 | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| `verda volume create`   | Create a block storage volume                |
-| `verda volume list`     | List volumes                                 |
-| `verda volume describe` | Show detailed info about a single volume     |
-| `verda volume action`   | Detach, rename, resize, clone, or delete     |
-| `verda volume trash`    | List deleted volumes (restorable within 96h) |
-
-
-### Instance Types, Images, Locations & Availability
-
-```bash
-# Browse instance types with specs and pricing
-verda instance-types
-verda instance-types --gpu             # GPU only
-verda instance-types --cpu             # CPU only
-verda instance-types --spot            # spot pricing
-
-# List all OS images
-verda images
-verda images --type 1V100.6V          # compatible with instance type
-verda images --category ubuntu         # filter by category
-
-# List datacenter locations
-verda locations
-
-# Check capacity
-verda availability                     # full matrix
-verda availability --location FIN-01   # specific location
-verda availability --type 1V100.6V     # specific type
-verda availability --spot              # spot only
 ```
 
-### Cost & Billing
+## AI Agent Integration (MCP) — Beta
 
-```bash
-# Estimate costs before creating
-verda cost estimate --type 1V100.6V --os-volume 100 --storage 500
-verda cost estimate --type 1V100.6V --spot
+The Verda CLI includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets AI agents (Claude Code, Cursor, etc.) manage your infrastructure through natural language. This feature is in **beta** — feedback welcome.
 
-# See what your running instances are costing you
-verda cost running
+### Setup
 
-# Account balance
-verda cost balance
+```json
+{
+  "mcpServers": {
+    "verda": {
+      "command": "verda",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
 ```
 
-### SSH Keys & Startup Scripts
-
-
-| Command                                    | Description            |
-| ------------------------------------------ | ---------------------- |
-| `verda ssh-key list / add / delete`        | Manage SSH keys        |
-| `verda startup-script list / add / delete` | Manage startup scripts |
-
-
-### Settings
-
-
-| Command                         | Description                    |
-| ------------------------------- | ------------------------------ |
-| `verda settings theme`          | View or change the color theme |
-| `verda settings theme --select` | Interactive theme picker       |
-
-
-Available themes: `default`, `dracula`, `catppuccin`, `catppuccin-latte`, `nord`, `tokyonight`, `github-light`, `solarized-light`
-
-### Update
-
-
-| Command                         | Description                                       |
-| ------------------------------- | ------------------------------------------------- |
-| `verda update`                  | Update to the latest version                      |
-| `verda update --version v1.0.0` | Install a specific version (upgrade or downgrade) |
-| `verda update --list`           | List available versions                           |
+Add this to your agent's MCP config:
 
+| Agent | Config file |
+|-------|------------|
+| Claude Code | `.mcp.json` in project root |
+| Cursor | `~/.cursor/mcp.json` |
 
-### Auth
+### Usage
 
+Once configured, just talk to your agent:
 
-| Command                  | Description                               |
-| ------------------------ | ----------------------------------------- |
-| `verda auth login`       | Save API credentials (interactive wizard) |
-| `verda auth show`        | Show active profile and credentials path  |
-| `verda auth use PROFILE` | Switch active auth profile                |
-
-
-### Shell Completion
-
-```bash
-# Bash
-source <(verda completion bash)
-
-# Zsh (add to ~/.zshrc or run once)
-verda completion zsh > "${fpath[1]}/_verda"
-
-# Fish
-verda completion fish | source
 ```
-
-## Global Flags
-
-
-| Flag              | Description                                           |
-| ----------------- | ----------------------------------------------------- |
-| `--output, -o`    | Output format: `table`, `json`, `yaml` (default: table) |
-| `--debug`         | Enable debug output (API request/response details)    |
-| `--timeout`       | HTTP request timeout (default: 30s)                   |
-| `--base-url`      | Override API base URL                                 |
-| `--config`        | Path to config file (default: `~/.verda/config.yaml`) |
-
-### Structured Output
-
-All list and describe commands support `--output json` and `--output yaml` for scripting:
-
-```bash
-# Pipe to jq
-verda vm list -o json | jq '.[].hostname'
-
-# YAML output
-verda volume describe vol-123 -o yaml
-
-# Use in CI/CD scripts
-INSTANCE_ID=$(verda vm list -o json | jq -r '.[0].id')
+"What GPU types are available right now?"
+"How much does an 8x H100 cost per hour?"
+"I need a cheap GPU for testing — what's the best option?"
+"Deploy a V100 GPU VM with 100GB OS volume"
+"Show my running VMs and what they're costing me"
+"Shut down my training VM"
 ```
 
-### Wait for Operations
+Credentials are shared with the CLI — run `verda auth login` first.
 
-Async commands support `--wait` to poll until completion:
+### Agent Mode
+
+For scripts and agents that use the CLI directly (without MCP):
 
 ```bash
-verda vm create --hostname gpu-runner --wait --wait-timeout 10m
-verda vm action --id abc-123 --wait
-verda volume create --name data --size 500 --wait
+verda --agent vm list                  # JSON output, no prompts
+verda --agent vm create ...            # structured errors for missing flags
+verda --agent vm action --id X --action shutdown --yes
 ```
 
+See [Agent Error Format](docs/agent-errors.md) for the structured error specification.
 
 ## Configuration
 
-Credentials are stored in `~/.verda/credentials` (AWS-style INI format):
+Credentials are stored in `~/.verda/credentials` (INI format):
 
 ```ini
 [default]
@@ -306,9 +152,14 @@ verda_client_id     = your-client-id
 verda_client_secret = your-client-secret
 ```
 
-Settings (theme, etc.) are stored in `~/.verda/config.yaml`.
+Multiple profiles are supported — switch with `verda auth use PROFILE`.
+
+## Documentation
 
-Override the config directory with `VERDA_HOME` environment variable.
+| Doc | Description |
+|-----|-------------|
+| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples |
+| [Agent Error Format](docs/agent-errors.md) | Structured error specification for `--agent` mode |
 
 ## Contributing