zettagrid-vmware-mcp

Zettagrid VMware MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Zettagrid's VMware Cloud Director infrastructure across all Australian zones. This server enables AI assistants to perform complete tenant organization administration through the Cloud Director API.

Features

• Multi-Zone Support: Manage resources across all Australian Zettagrid zones (Sydney, Melbourne, Perth, Brisbane, Adelaide, Darwin)
• Comprehensive API Coverage: Full tenant organization lifecycle management
• OAuth Authentication: Secure API token refresh and session management
• Type-Safe Operations: Complete TypeScript implementation with vCloud Director schema compliance
• Error Handling: Robust retry logic and graceful error recovery
• Performance Optimized: Connection pooling, caching, and efficient API usage

Installation

Prerequisites

• Node.js 18.0 or later
• npm or yarn package manager
• Valid Zettagrid API token and organization access - See token instructions https://customer.support.zettagrid.com/servicedesk/customer/portal/9/article/1270415361

Quick Start

1. Install the package:

npm install @zettagrid/vmware-mcp

2. Configure environment variables:

cp .env.example .env
# Edit .env with your Zettagrid credentials

3. Run the MCP server:

npm start

Development Setup

1. Clone the repository:

git clone https://github.com/zettagrid/zettagrid-vmware-mcp.git
cd zettagrid-vmware-mcp

2. Install dependencies:

npm install

3. Configure environment:

cp .env.example .env
# Configure your zone credentials (see Configuration section)

4. Build the project:

npm run build

5. Run tests:

npm test

Configuration

Environment Variables

Create a .env file with your Zettagrid zone configurations:

# Organization Configuration
ZETTAGRID_ORGANIZATION=your-organization-name
ZETTAGRID_DEFAULT_ZONE=perth
ZETTAGRID_API_VERSION=39.1

# Zone API Tokens (configure the zones you need)
ZETTAGRID_API_TOKEN_PERTH=your-perth-api-token
ZETTAGRID_API_TOKEN_SYDNEY=your-sydney-api-token
ZETTAGRID_API_TOKEN_MELBOURNE=your-melbourne-api-token
ZETTAGRID_API_TOKEN_BRISBANE=your-brisbane-api-token
ZETTAGRID_API_TOKEN_ADELAIDE=your-adelaide-api-token
ZETTAGRID_API_TOKEN_DARWIN=your-darwin-api-token

# Performance Settings (optional)
ZETTAGRID_TIMEOUT=30000
ZETTAGRID_RETRY_ATTEMPTS=3
ZETTAGRID_ENABLE_CACHING=true

# Debug Settings (optional)
DEBUG_LEVEL=info
ZETTAGRID_DEBUG=false

Note: API and OAuth endpoints are automatically generated based on the standard Zettagrid format:

• API endpoint: https://mycloud.{zone-code}.zettagrid.com/api
• OAuth endpoint: https://mycloud.{zone-code}.zettagrid.com/oauth/tenant/{org}/token

All Supported Zones

Configure any or all of the following Australian zones:

Zone	API Token Variable	Auto-Generated Endpoint
Sydney	ZETTAGRID_API_TOKEN_SYDNEY	https://mycloud.syd.zettagrid.com/api
Melbourne	ZETTAGRID_API_TOKEN_MELBOURNE	https://mycloud.mel.zettagrid.com/api
Perth	ZETTAGRID_API_TOKEN_PERTH	https://mycloud.per.zettagrid.com/api
Brisbane	ZETTAGRID_API_TOKEN_BRISBANE	https://mycloud.bri.zettagrid.com/api
Adelaide	ZETTAGRID_API_TOKEN_ADELAIDE	https://mycloud.adl.zettagrid.com/api
Darwin	ZETTAGRID_API_TOKEN_DARWIN	https://mycloud.dar.zettagrid.com/api

Usage

Testing Connectivity

Test your configuration with the built-in connectivity test:

npm run test:connectivity
# or manually:
npx tsx src/examples/connectivity-test.ts

This will validate:

• Zone configuration
• Network connectivity
• OAuth authentication
• Basic API operations
• Health status

MCP Client Configuration

Claude Desktop Configuration

Add the Zettagrid MCP server to your Claude Desktop configuration:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zettagrid-vmware": {
      "command": "node",
      "args": ["/path/to/zettagrid-vmware-mcp/build/index.js"],
      "env": {
        "ZETTAGRID_ORGANIZATION": "your-organization-name",
        "ZETTAGRID_DEFAULT_ZONE": "perth",
        "ZETTAGRID_API_VERSION": "39.1",
        "ZETTAGRID_API_TOKEN_PERTH": "your-perth-token",
        "ZETTAGRID_TIMEOUT": "30000",
        "ZETTAGRID_RETRY_ATTEMPTS": "3",
        "ZETTAGRID_ENABLE_CACHING": "true",
        "DEBUG_LEVEL": "info"
      }
    }
  }
}

Cursor MCP Configuration

Configure Cursor to use the Zettagrid MCP server by adding to your Cursor settings:

Cursor Settings → Extensions → MCP Servers

{
  "mcp.servers": {
    "zettagrid-vmware": {
      "command": "node",
      "args": ["/path/to/zettagrid-vmware-mcp/build/index.js"],
      "env": {
        "ZETTAGRID_ORGANIZATION": "your-organization-name",
        "ZETTAGRID_DEFAULT_ZONE": "perth",
        "ZETTAGRID_API_VERSION": "39.1",
        "ZETTAGRID_API_TOKEN_PERTH": "your-perth-token",
        "ZETTAGRID_TIMEOUT": "30000",
        "ZETTAGRID_RETRY_ATTEMPTS": "3",
        "ZETTAGRID_ENABLE_CACHING": "true",
        "DEBUG_LEVEL": "info"
      }
    }
  }
}

Development Mode Configuration

For development with npm run dev:

{
  "mcpServers": {
    "zettagrid-vmware-dev": {
      "command": "npx",
      "args": ["tsx", "/path/to/zettagrid-vmware-mcp/src/index.ts"],
      "cwd": "/path/to/zettagrid-vmware-mcp",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

Multi-Zone Configuration

To configure multiple zones, add all zone credentials to the env section:

{
  "env": {
    "ZETTAGRID_ORGANIZATION": "your-organization-name",
    "ZETTAGRID_DEFAULT_ZONE": "perth",
    "ZETTAGRID_API_VERSION": "39.1",
    
    "ZETTAGRID_API_TOKEN_SYDNEY": "your-sydney-token",
    "ZETTAGRID_API_TOKEN_MELBOURNE": "your-melbourne-token",
    "ZETTAGRID_API_TOKEN_PERTH": "your-perth-token",
    "ZETTAGRID_API_TOKEN_BRISBANE": "your-brisbane-token",
    "ZETTAGRID_API_TOKEN_ADELAIDE": "your-adelaide-token",
    "ZETTAGRID_API_TOKEN_DARWIN": "your-darwin-token"
  }
}

MCP Server Integration

The server provides comprehensive MCP tools for cloud management:

Organization Management

• list_organizations - List all accessible organizations
• get_organization - Get organization details and settings
• update_organization_settings - Modify organization configuration

Virtual Data Center (VDC) Operations

• list_vdcs - List virtual data centers
• get_vdc - Get VDC details and capabilities
• show_vdc_resources - Show VDC resource allocation and usage table (RAM, vCPU, Storage)
• get_vdc_compute_policies - Retrieve compute policies and limits

vApp Lifecycle Management

• list_vapps - List virtual applications
• get_vapp - Get vApp configuration and status
• power_on_vapp - Start vApp
• power_off_vapp - Stop vApp
• deploy_vapp - Deploy vApp from template

Virtual Machine Operations

• list_vms - List virtual machines
• get_vm - Get VM details and configuration
• power_on_vm - Start virtual machine
• power_off_vm - Stop virtual machine
• get_vm_console - Get VM console access ticket

Storage Management

• list_disks - List independent disks
• create_disk - Create new storage disk
• attach_disk - Attach disk to VM

Network Configuration

• list_org_networks - List organization networks
• create_org_network - Create organization network

Firewall and Security

• list_edge_gateways - List edge gateways
• get_edge_gateway - Get edge gateway details and configuration
• list_firewall_rules - List firewall rules for an edge gateway
• create_firewall_rule - Create new firewall rule

API Client Usage

Use the Zettagrid client directly in your applications:

import { ZettagridClient } from '@zettagrid/vmware-mcp';

const client = new ZettagridClient();

// List organizations
const orgs = await client.listOrganizations('perth');
console.log(orgs.data);

// Get VDCs  
const vdcs = await client.listVdcs('perth');
console.log(vdcs.data);

// Zone information
const zoneInfo = await client.getZoneInfo('perth');
console.log(zoneInfo.data);

Authentication

OAuth Token Refresh Flow

The server implements Zettagrid's OAuth authentication flow:

1. API Token: Your initial Zettagrid API token
2. Token Refresh: Automatically exchanges the API token for an access token via OAuth
3. Session Management: Maintains authenticated sessions with automatic refresh
4. Multi-Zone: Independent authentication per zone

Authentication Process

sequenceDiagram
    participant Client as MCP Client
    participant Server as Zettagrid MCP
    participant OAuth as Zettagrid OAuth
    participant API as vCloud Director API
    
    Client->>Server: Request (with zone)
    Server->>OAuth: POST /oauth/tenant/{org}/token?grant_type=refresh_token&refresh_token={token}
    OAuth->>Server: access_token + expires_in
    Server->>API: API Request with Bearer {access_token}
    API->>Server: API Response
    Server->>Client: MCP Response

Zone Management

Multi-Zone Operations

The server supports operations across multiple zones:

// Default zone operation
const vdcs = await client.listVdcs();

// Specific zone operation  
const vdcsSydney = await client.listVdcs('sydney');
const vdcsPerth = await client.listVdcs('perth');

// Zone information
const zones = client.getZoneInfo();
console.log(zones.data.availableZones); // ['sydney', 'perth', ...]

Zone Health Monitoring

// Test zone connectivity
const healthCheck = await client.getHealthStatus();
console.log(healthCheck.data);

// Test specific zone
const zoneTest = await client.testZone('perth');
console.log(zoneTest.data);

Error Handling

The server implements comprehensive error handling:

Automatic Retry

• Network failures: 3 retry attempts with exponential backoff
• Rate limiting: Automatic backoff and retry
• Token expiration: Automatic re-authentication

Error Types

• ZONE_TEST_ERROR - Zone connectivity issues
• GET_ORGANIZATION_ERROR - Organization access problems
• LIST_VDCS_ERROR - VDC enumeration failures
• POWER_ON_VAPP_ERROR - vApp power operation failures

Error Response Format

{
  "success": false,
  "error": {
    "code": "GET_VDC_ERROR",
    "message": "Failed to get VDC",
    "details": { ... }
  },
  "metadata": {
    "zone": "perth",
    "organization": "Org_cloud1100009", 
    "timestamp": "2025-06-19T14:58:05.809Z"
  }
}

Security

Best Practices

• Environment Variables: Store all credentials in environment variables
• Token Security: API tokens are automatically refreshed and never logged
• HTTPS Enforcement: All communications use HTTPS/TLS
• Zone Isolation: Authentication is isolated per zone
• Audit Logging: All operations are logged for security auditing

Credential Management

• Never commit API tokens to version control
• Use different tokens per environment (dev/staging/prod)
• Rotate API tokens regularly
• Monitor token usage and access logs

Troubleshooting

Common Issues

Authentication Failures

# Check token validity
curl -X POST "https://mycloud.per.zettagrid.com/oauth/tenant/YourOrg/token?grant_type=refresh_token&refresh_token=YourToken" \
  -H "Accept: application/json"

Zone Connectivity Issues

# Test zone endpoint
npm run test:connectivity

Environment Configuration

# Validate environment variables
node -e "console.log(process.env.ZETTAGRID_API_TOKEN_PERTH ? 'Token configured' : 'Token missing')"

Debug Mode

Enable detailed logging:

DEBUG_LEVEL=debug ZETTAGRID_DEBUG=true npm run dev

Support

• Zettagrid: This MCP server is not officially supported by Zettagrid and provided with warranties of no kind.
• Documentation: This readme.md
• Issues: Report bugs via GitHub Issues
• Community: Join the discussion in GitHub Discussions

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0 (2025-06-19)

• Initial release
• Multi-zone support for all Australian Zettagrid zones
• OAuth authentication with automatic token refresh
• Comprehensive vCloud Director API coverage
• TypeScript implementation with full type safety
• Live testing against Perth zone infrastructure
• Complete MCP tool suite for cloud management

---

Zettagrid VMware MCP Server - Comprehensive cloud infrastructure management through AI assistants.