# 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.