vme-mcp-server/dist/README.md

An intelligent Model Context Protocol (MCP) server that transforms HPE VM Essentials (VME) infrastructure management into natural language conversations. Provision VMs, manage resources, and control your infrastructure through simple English commands with

# VME MCP Server

Transform HPE VM Essentials infrastructure management into conversational AI interactions with Claude.

## Installation

```bash
npm install -g vme-mcp-server
```

## Quick Start

### 1. Configure VME API Access

**Option A: Command Line Arguments (Recommended)**

```bash
vme-mcp-server --endpoint https://your-hpe-vme-instance.com/api --token your-bearer-token
# Or use short forms:
vme-mcp-server -e https://your-hpe-vme-instance.com/api -t your-bearer-token
```

**Option B: Environment Variables**

```bash
export VME_ENDPOINT=https://your-hpe-vme-instance.com/api
export VME_TOKEN=your-bearer-token
```

**Option C: Configuration File**

Create a `.env` file:

```bash
# HPE VM Essentials Configuration
VME_ENDPOINT=https://your-hpe-vme-instance.com/api
VME_TOKEN=your-bearer-token

# Privacy Controls (Optional)
ENABLE_AI_TRAINING_DATA=false
AI_TRAINING_DATA_RETENTION_DAYS=30
```

**Priority Order**: Command line arguments → Environment variables → .env files

### 2. Add to Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

**Option A: With Command Line Arguments**

```json
{
  "mcpServers": {
    "vme": {
      "command": "vme-mcp-server",
      "args": ["--endpoint", "https://your-hpe-vme-instance.com/api", "--token", "your-bearer-token"]
    }
  }
}
```

**Option B: With Environment Variables**

```json
{
  "mcpServers": {
    "vme": {
      "command": "vme-mcp-server",
      "env": {
        "VME_ENDPOINT": "https://your-hpe-vme-instance.com/api",
        "VME_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

**Option C: Using .env File**

```json
{
  "mcpServers": {
    "vme": {
      "command": "vme-mcp-server"
    }
  }
}
```

### 3. Start Claude Desktop

Restart Claude Desktop. You should see the VME MCP Server tools available.

## Usage Examples

### Natural Language VM Creation

```
"Create 3 Ubuntu VMs named web01 through web03 spread across cluster nodes"
```

```
"Create a Rocky Linux VM called db-server with 4GB RAM"
```

```
"Show me available VM templates and service plans"
```

### Supported Operations

- **Resource Discovery**: Get available service plans, OS templates, zones, and groups
- **VM Creation**: Create single or multiple VMs with intelligent naming
- **OS Resolution**: Automatically select latest stable OS versions
- **Node Distribution**: Auto-placement, spread, or specific node targeting
- **Intent Recognition**: Natural language understanding with 93%+ accuracy

## Features

### Intelligent Resource Discovery
- Unified API consolidating multiple HPE VM Essentials endpoints
- Intent-aware responses based on context
- Semantic organization of compute vs infrastructure resources

### Natural Language Processing
- Parse complex VM provisioning requests
- Extract VM names, OS templates, sizes, zones from natural language
- Handle range patterns like "web01->web03" automatically
- Confidence scoring for reliability

### Privacy-First Design
- Optional AI training data collection (disabled by default)
- Granular control over what data is logged
- Configurable retention periods
- All training data excluded from version control

## Configuration

### Environment Variable Loading (Global Install Support)

The server automatically searches for `.env` files in multiple locations:

1. **Current directory**: `./env` (for local development)
2. **Home directory**: `~/.env` (for global installs)
3. **Config directory**: `~/.config/vme-mcp-server/.env`
4. **Documents folder**: `~/Documents/.env.vme-mcp-server`

### Recommended Configuration Methods

**Method 1: Command Line Arguments (Recommended)**

```bash
vme-mcp-server --endpoint https://your-hpe-vme-instance.com/api --token your-bearer-token
```

**Method 2: Direct Environment Variables**

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "vme-mcp-server": {
      "command": "vme-mcp-server",
      "env": {
        "VME_ENDPOINT": "https://your-hpe-vme-instance.com/api",
        "VME_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

**Method 3: .env File (Good for Local Development)**

Create `.env` file in any of the supported locations above.

### Required Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `VME_ENDPOINT` | HPE VM Essentials API endpoint | `https://vme.company.com/api` |
| `VME_TOKEN` | Bearer token for authentication | `your-bearer-token` |

### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_AI_TRAINING_DATA` | `false` | Enable interaction logging for AI improvements |
| `AI_TRAINING_DATA_RETENTION_DAYS` | `30` | How long to keep training data |
| `AI_TRAINING_DATA_FIELDS` | See docs | Which fields to include in training data |

## Troubleshooting

### Common Issues

**"No tools available"**
- Ensure Claude Desktop is restarted after configuration
- Check that the `vme-mcp-server` command is in your PATH
- Verify MCP configuration syntax in `claude_desktop_config.json`

**"API connection failed"**
- Verify `VME_ENDPOINT` is correct and accessible
- Check that `VME_TOKEN` has sufficient permissions
- Ensure network connectivity to HPE VM Essentials infrastructure

**"VM creation failed"**
- Verify user permissions in HPE VM Essentials for VM creation
- Check that specified service plans and templates exist
- Ensure target group/zone has available resources

### Getting Help

- Check the `.env.example` file for configuration templates
- Review error messages for specific guidance
- Ensure HPE VM Essentials infrastructure is accessible and properly configured

## Architecture

This MCP server prioritizes natural language understanding over traditional REST API mappings. It provides:

- **Context-aware operations** that understand user intent
- **Intelligent resource discovery** with semantic organization
- **Role-based access** with dynamic tool schemas
- **Privacy-by-design** data collection with user control

Built with TypeScript and the Model Context Protocol for seamless Claude integration.

## Version

Current version: 0.1.11

For development documentation and contribution guidelines, see the project repository.