MCP/mcvsphere
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: MCP:main
Branches Tags
MCP:main
MCP:feature/oauth-authentication
MCP:v0.2.3
MCP:v0.2.2
..
compare: MCP:feature/oauth-authentication
Branches Tags
MCP:main
MCP:feature/oauth-authentication
MCP:v0.2.3
MCP:v0.2.2

No commits in common. "main" and "feature/oauth-authentication" have entirely different histories.
main ... feature/oa

49 changed files with 732 additions and 8800 deletions
Show Stats Expand all files Collapse all files

82
.env.oauth.example
View File

@ -1,82 +0,0 @@
# mcvsphere OAuth Configuration Template
# Copy to .env and configure for your environment
#
# Usage:
# cp .env.oauth.example .env
# # Edit .env with your values
# docker compose -f docker-compose.oauth-standalone.yml up -d
# ─────────────────────────────────────────────────────────────────────────────
# Docker Compose
# ─────────────────────────────────────────────────────────────────────────────
COMPOSE_PROJECT_NAME=mcvsphere
# ─────────────────────────────────────────────────────────────────────────────
# vCenter Connection (Required)
# ─────────────────────────────────────────────────────────────────────────────
VCENTER_HOST=vcenter.example.com
VCENTER_USER=mcpservice@vsphere.local
VCENTER_PASSWORD=your-secure-password
# Optional: Skip SSL verification (dev only - use false in production)
VCENTER_INSECURE=false
# Optional: Specify defaults (auto-detected if not set)
# VCENTER_DATACENTER=Datacenter
# VCENTER_CLUSTER=Cluster
# VCENTER_DATASTORE=datastore1
# VCENTER_NETWORK=VM Network
# ─────────────────────────────────────────────────────────────────────────────
# MCP Transport (Required for OAuth)
# ─────────────────────────────────────────────────────────────────────────────
MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8080
# Your public domain (must match Caddy proxy)
MCP_DOMAIN=mcp.example.com
# TLS mode: 'internal' for self-signed (dev), remove for auto HTTPS (prod)
MCP_TLS_MODE=internal
# ─────────────────────────────────────────────────────────────────────────────
# OAuth / OIDC Provider (Required)
# ─────────────────────────────────────────────────────────────────────────────
OAUTH_ENABLED=true
# OIDC Discovery URL (ends with /.well-known/openid-configuration)
# Examples:
# Authentik: https://auth.example.com/application/o/mcvsphere/
# Keycloak: https://keycloak.example.com/realms/myrealm
# Auth0: https://myapp.auth0.com/
# Okta: https://myorg.okta.com/oauth2/default
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
# OAuth Client Credentials (from your OIDC provider)
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
# Public callback URL (must be accessible from browser)
OAUTH_BASE_URL=https://mcp.example.com
# ─────────────────────────────────────────────────────────────────────────────
# RBAC Permission Groups
# ─────────────────────────────────────────────────────────────────────────────
# Create these groups in your OIDC provider and assign users:
#
# | Group | Access Level |
# |------------------------|---------------------------------|
# | vsphere-super-admins | Full control (all 94 tools) |
# | vsphere-host-admins | Host operations + VM management |
# | vsphere-admins | VM lifecycle management |
# | vsphere-operators | Power ops + snapshots |
# | vsphere-readers | Read-only |
#
# Users without any vsphere-* group will be denied access (default-deny).
# ─────────────────────────────────────────────────────────────────────────────
# Optional Settings
# ─────────────────────────────────────────────────────────────────────────────
# LOG_LEVEL=INFO
# MCVSPHERE_VERSION=0.2.2

14
Dockerfile
View File

@ -48,11 +48,8 @@ ENV PATH="/app/.venv/bin:$PATH"
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
# Default transport - override with MCP_TRANSPORT env var
# stdio: Direct CLI usage (default for local)
# sse: Server-Sent Events (legacy HTTP)
# streamable-http: HTTP with OAuth support (required for multi-user)
ENV MCP_TRANSPORT=streamable-http
# Default to SSE transport for Docker
ENV MCP_TRANSPORT=sse
ENV MCP_HOST=0.0.0.0
ENV MCP_PORT=8080
@ -61,9 +58,10 @@ USER mcpuser
EXPOSE 8080
# Health check - works with both SSE and streamable-http
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/.well-known/oauth-authorization-server')" || exit 1
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080')" || exit 1
# Run the MCP server - transport configured via environment
# Run the MCP server
ENTRYPOINT ["mcvsphere"]
CMD ["--transport", "sse"]

504
OAUTH-ARCHITECTURE.md
View File

@ -1,17 +1,17 @@
# OAuth & RBAC Architecture for mcvsphere
# OAuth Architecture for vSphere MCP Server
## Overview
## The Problem
mcvsphere supports multi-user OAuth 2.1 authentication with Role-Based Access Control (RBAC). This enables:
We need to add authentication to the MCP server so that:
1. Users authenticate via **OAuth 2.1 / OIDC** (using Authentik as IdP)
2. The MCP server knows WHO is making requests (for audit logging)
3. vCenter permissions are respected per-user
1. **Single Sign-On** via any OIDC provider (Authentik, Keycloak, Auth0, etc.)
2. **User Identity** for audit logging - know WHO made each request
3. **Group-Based Permissions** - control what users can do based on OAuth groups
4. **Audit Trail** - every tool invocation logged with user identity and timing
**Challenge:** vCenter 7.0.3 doesn't support OAuth token exchange (RFC 8693), so we can't pass OAuth tokens directly to vCenter.
---
## Architecture
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
@ -22,352 +22,360 @@ mcvsphere supports multi-user OAuth 2.1 authentication with Role-Based Access Co
│ (browser opens for login)
│
┌────────────────────────────▼────────────────────────────────────┐
│ OIDC Provider │
│ (Authentik, Keycloak, Auth0, etc.) │
│ Authentik │
│ (Self-hosted OIDC IdP) │
│ │
│ - Issues JWT access tokens │
│ - Validates user credentials │
│ - Includes groups claim in token │
│ - Includes user identity in token (sub, email, groups) │
└────────────────────────────┬────────────────────────────────────┘
│
│ 2. JWT Bearer token
│ Authorization: Bearer <jwt>
│
┌────────────────────────────▼────────────────────────────────────┐
│ mcvsphere │
│ vSphere MCP Server │
│ (FastMCP + pyvmomi) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ OIDCProxy (FastMCP) │ │
│ │ - Validates JWT signature via JWKS endpoint │ │
│ │ - Extracts user identity (preferred_username, email) │ │
│ │ - Extracts groups from token claims │ │
│ │ - Validates JWT signature via Authentik JWKS │ │
│ │ - Extracts user identity (preferred_username) │ │
│ │ - Makes user available via ctx.request_context.user │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ RBACMiddleware │ │
│ │ - Intercepts ALL tool calls via on_call_tool() │ │
│ │ - Maps OAuth groups → Permission levels │ │
│ │ - Denies access if user lacks required permission │ │
│ │ - Logs audit events with user identity │ │
│ │ Credential Broker │ │
│ │ - Maps OAuth user → vCenter credentials │ │
│ │ - Caches pyvmomi connections per-user │ │
│ │ - Retrieves passwords from Vault / env vars │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ VMware Tools (94) │ │
│ │ - Execute vCenter/ESXi operations via pyvmomi │ │
│ │ - Single service account connection to vCenter │ │
│ │ Audit Logger │ │
│ │ - Logs all tool invocations with OAuth identity │ │
│ │ - "User ryan@example.com powered on VM web-server" │ │
│ └─────────────────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│
│ 3. pyvmomi (service account)
│ 3. pyvmomi (as mapped user)
│
┌────────────────────────────▼────────────────────────────────────┐
│ vCenter / ESXi │
│ - Receives API calls as service account │
│ - mcvsphere audit logs show real user identity │
│ vCenter 7.0.3 │
│ - Receives API calls as the actual user │
│ - Native audit logs show real user identity │
│ - vCenter permissions apply naturally │
└─────────────────────────────────────────────────────────────────┘
```
---
## RBAC Permission Model
## User Mapping Strategies
### Permission Levels
Since we can't exchange OAuth tokens for vCenter tokens, we need a "credential broker":
mcvsphere defines 5 permission levels, from least to most privileged:
| Strategy | How it Works | Security | Use Case |
|----------|--------------|----------|----------|
| **Service Account** | All requests use one vCenter admin account | Medium | Simple/dev |
| **Per-User Mapping** | Map OAuth username → vCenter credentials from Vault | High | Production |
| **LDAP Sync** | Same username/password in Authentik and vCenter SSO | Medium | AD environments |
| Level | Description | Example Tools |
|-------|-------------|---------------|
| `READ_ONLY` | View-only operations | `list_vms`, `get_vm_info`, `vm_screenshot` |
| `POWER_OPS` | Power and snapshot operations | `power_on`, `create_snapshot`, `reboot_guest` |
| `VM_LIFECYCLE` | Create/delete/modify VMs | `create_vm`, `clone_vm`, `add_disk`, `deploy_ovf` |
| `HOST_ADMIN` | ESXi host operations | `reboot_host`, `enter_maintenance_mode` |
| `FULL_ADMIN` | Everything including guest OS ops | `run_command_in_guest`, `restart_service` |
### OAuth Groups → Permissions
Users are granted permissions based on their OAuth group memberships:
| OAuth Group | Permissions Granted |
|-------------|---------------------|
| `vsphere-readers` | READ_ONLY |
| `vsphere-operators` | READ_ONLY, POWER_OPS |
| `vsphere-admins` | READ_ONLY, POWER_OPS, VM_LIFECYCLE |
| `vsphere-host-admins` | READ_ONLY, POWER_OPS, VM_LIFECYCLE, HOST_ADMIN |
| `vsphere-super-admins` | ALL (full access) |
**Security Note:** Users with NO recognized groups are denied ALL access. There is no default permission.
### Tool → Permission Mapping
All 94 tools are mapped to permission levels in `src/mcvsphere/permissions.py`:
### Recommended: Per-User Mapping with Fallback
```python
# READ_ONLY - 32 tools
"list_vms", "get_vm_info", "list_snapshots", "get_vm_stats", ...
class CredentialBroker:
"""Maps OAuth users to vCenter credentials."""
# POWER_OPS - 14 tools
"power_on", "power_off", "create_snapshot", "revert_to_snapshot", ...
def __init__(self, vcenter_host: str, fallback_user: str = None, fallback_password: str = None):
self.vcenter_host = vcenter_host
self.fallback_user = fallback_user # Service account fallback
self.fallback_password = fallback_password
self._connections: dict[str, ServiceInstance] = {}
# VM_LIFECYCLE - 33 tools
"create_vm", "clone_vm", "delete_vm", "add_disk", "deploy_ovf", ...
def get_connection_for_user(self, oauth_user: dict) -> ServiceInstance:
"""Get pyvmomi connection for this OAuth user."""
username = oauth_user.get("preferred_username")
# HOST_ADMIN - 6 tools
"enter_maintenance_mode", "reboot_host", "shutdown_host", ...
# Try per-user credentials first
try:
vcenter_creds = self._lookup_credentials(username)
return self._get_or_create_connection(
vcenter_creds["user"],
vcenter_creds["password"]
)
except KeyError:
# Fall back to service account
if self.fallback_user:
return self._get_or_create_connection(
self.fallback_user,
self.fallback_password
)
raise ValueError(f"No vCenter credentials for user: {username}")
# FULL_ADMIN - 11 tools
"run_command_in_guest", "write_guest_file", "restart_service", ...
def _lookup_credentials(self, username: str) -> dict:
"""Look up vCenter credentials for OAuth user."""
# Option 1: Environment variable
env_key = f"VCENTER_PASSWORD_{username.upper().replace('@', '_').replace('.', '_')}"
if password := os.environ.get(env_key):
return {"user": f"{username}@vsphere.local", "password": password}
# Option 2: HashiCorp Vault (production)
# return vault_client.read(f"secret/vcenter/users/{username}")
raise KeyError(f"No credentials found for {username}")
```
---
## Implementation Details
## FastMCP OAuth Integration
### Key Files
| File | Purpose |
|------|---------|
| `src/mcvsphere/auth.py` | OIDCProxy configuration |
| `src/mcvsphere/permissions.py` | Permission levels and tool mappings |
| `src/mcvsphere/middleware.py` | RBACMiddleware implementation |
| `src/mcvsphere/audit.py` | Audit logging with user context |
| `src/mcvsphere/server.py` | Server setup with OAuth + RBAC |
### RBACMiddleware Flow
### 1. Add OIDCProxy to server.py
```python
class RBACMiddleware(Middleware):
"""Intercepts all tool calls to enforce permissions."""
import os
from fastmcp import FastMCP
from fastmcp.server.auth import OIDCProxy
async def on_call_tool(self, context, call_next):
# 1. Extract user from OAuth token
claims = self._extract_user_from_context(context.fastmcp_context)
username = claims.get("preferred_username", "unknown")
groups = claims.get("groups", [])
# Configure OAuth with Authentik
auth = OIDCProxy(
# Authentik OIDC Discovery URL
config_url=os.environ["AUTHENTIK_OIDC_URL"],
# e.g., "https://auth.example.com/application/o/vsphere-mcp/.well-known/openid-configuration"
# 2. Check permission
tool_name = context.message.name
if not check_permission(tool_name, groups):
required = get_required_permission(tool_name)
audit_permission_denied(tool_name, {...}, required.value)
raise PermissionDeniedError(username, tool_name, required)
# Application credentials from Authentik
client_id=os.environ["AUTHENTIK_CLIENT_ID"],
client_secret=os.environ["AUTHENTIK_CLIENT_SECRET"],
# 3. Execute tool with timing
start = time.perf_counter()
result = await call_next(context)
duration_ms = (time.perf_counter() - start) * 1000
# MCP Server base URL (for redirects)
base_url=os.environ.get("MCP_BASE_URL", "http://localhost:8000"),
# 4. Audit log
audit_log(tool_name, {...}, result="success", duration_ms=duration_ms)
return result
# Token validation
required_scopes=["openid", "profile", "email"],
# Allow Claude Code localhost redirects
allowed_client_redirect_uris=["http://localhost:*", "http://127.0.0.1:*"],
)
# Create MCP server with OAuth
mcp = FastMCP(
"vSphere MCP Server",
auth=auth,
# Use Streamable HTTP transport for OAuth
)
```
### Audit Log Format
### 2. Access User Identity in Tools
```json
{
"timestamp": "2025-12-27T08:15:32.123456+00:00",
"user": "ryan@example.com",
"groups": ["vsphere-admins", "vsphere-operators"],
"tool": "power_on",
"args": {"vm_name": "web-server"},
"duration_ms": 1234.56,
"result": "success"
}
```
```python
from fastmcp import Context
Permission denied events:
```json
{
"timestamp": "2025-12-27T08:15:32.123456+00:00",
"user": "guest@example.com",
"groups": ["vsphere-readers"],
"tool": "delete_vm",
"args": {"vm_name": "web-server"},
"required_permission": "vm_lifecycle",
"event": "PERMISSION_DENIED"
}
@mcp.tool()
async def power_on_vm(ctx: Context, vm_name: str) -> str:
"""Power on a virtual machine."""
# Get authenticated user from OAuth token
user = ctx.request_context.user
username = user.get("preferred_username", user.get("sub"))
# Get vCenter connection for this user
broker = get_credential_broker()
connection = broker.get_connection_for_user(user)
# Execute operation
content = connection.RetrieveContent()
vm = find_vm(content, vm_name)
vm.PowerOnVM_Task()
# Audit log
logger.info(f"User {username} powered on VM {vm_name}")
return f"VM '{vm_name}' is powering on"
```
---
## Configuration
## MCP Transport: Streamable HTTP
### Environment Variables
OAuth requires HTTP transport (not stdio). Use Streamable HTTP:
```python
# In server.py or via environment
mcp = FastMCP(
"vSphere MCP Server",
auth=auth,
)
def main():
# Run with HTTP transport for OAuth support
mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)
```
**Transport characteristics:**
- Single HTTP endpoint (`/mcp`)
- POST requests with JSON-RPC body
- Server-Sent Events (SSE) for streaming responses
- `Authorization: Bearer <token>` header on every request
- `Mcp-Session-Id` header for session continuity
---
## Environment Variables
```bash
# ═══════════════════════════════════════════════════════════════
# OAuth Configuration
# ═══════════════════════════════════════════════════════════════
OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
OAUTH_CLIENT_ID=<from-oidc-provider>
OAUTH_CLIENT_SECRET=<from-oidc-provider>
OAUTH_BASE_URL=https://mcp.example.com # Public URL for callbacks
OAUTH_SCOPES='["openid", "profile", "email", "groups"]'
# Authentik OIDC
AUTHENTIK_OIDC_URL=https://auth.example.com/application/o/vsphere-mcp/.well-known/openid-configuration
AUTHENTIK_CLIENT_ID=<from-authentik-application>
AUTHENTIK_CLIENT_SECRET=<from-authentik-application>
# ═══════════════════════════════════════════════════════════════
# Transport (must be HTTP for OAuth)
# ═══════════════════════════════════════════════════════════════
# MCP Server
MCP_BASE_URL=https://mcp.example.com # Public URL for OAuth redirects
MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8080
# ═══════════════════════════════════════════════════════════════
# vCenter Connection (service account)
# ═══════════════════════════════════════════════════════════════
# vCenter Connection (service account fallback)
VCENTER_HOST=vcenter.example.com
VCENTER_USER=svc-mcvsphere@vsphere.local
VCENTER_USER=svc-mcp@vsphere.local
VCENTER_PASSWORD=<service-account-password>
VCENTER_INSECURE=false
VCENTER_INSECURE=true
# ═══════════════════════════════════════════════════════════════
# Optional
# ═══════════════════════════════════════════════════════════════
LOG_LEVEL=INFO
```
# Per-user credentials (optional, for testing)
VCENTER_PASSWORD_RYAN=<ryan's-vcenter-password>
VCENTER_PASSWORD_ALICE=<alice's-vcenter-password>
### Server Startup Banner
When OAuth is enabled, the server shows:
```
mcvsphere v0.2.1
────────────────────────────────────────
Starting HTTP transport on 0.0.0.0:8080
OAuth: ENABLED via https://auth.example.com/application/o/mcvsphere/
RBAC: ENABLED - permissions enforced via groups
────────────────────────────────────────
# User Mapping Mode
USER_MAPPING_MODE=service_account # or 'per_user', 'ldap_sync'
```
---
## OIDC Provider Setup
### Authentik (Recommended)
## Authentik Setup (Quick Reference)
1. **Create OAuth2/OIDC Provider:**
- Name: `mcvsphere`
- Client Type: **Confidential**
- Name: `vsphere-mcp`
- Client Type: Confidential
- Redirect URIs:
- `http://localhost:*/callback` (for local dev)
- `http://localhost:*/callback`
- `https://mcp.example.com/auth/callback`
- Signing Key: Select RS256 certificate
- Scopes: `openid`, `profile`, `email`
- Signing Key: Select or create RS256 key
2. **Create Application:**
- Name: `mcvsphere`
- Slug: `mcvsphere`
- Provider: Select provider from step 1
- Name: `vSphere MCP Server`
- Slug: `vsphere-mcp`
- Provider: Select the provider above
- Note the **Client ID** and **Client Secret**
3. **Create Groups:**
- `vsphere-readers`
- `vsphere-operators`
- `vsphere-admins`
- `vsphere-host-admins`
- `vsphere-super-admins`
4. **Add Scope Mapping for Groups:**
- Ensure `groups` claim is included in tokens
- Authentik includes this by default
5. **Note Credentials:**
- Copy Client ID and Client Secret
- Discovery URL: `https://auth.example.com/application/o/mcvsphere/.well-known/openid-configuration`
### Other Providers
The same pattern works with Keycloak, Auth0, Okta, etc. Key requirements:
- OIDC Discovery endpoint (`.well-known/openid-configuration`)
- JWT access tokens (not opaque)
- `groups` claim in tokens with group names
3. **Configure Groups (optional):**
- `vsphere-admins` - Full access
- `vsphere-operators` - Limited access
- Groups are included in JWT `groups` claim
---
## OAuth Flow
## OAuth Flow (End-to-End)
```
1. Client connects to mcvsphere
→ POST /mcp (no auth)
→ Server returns 401 + OAuth metadata URL
1. Claude Code connects to MCP Server
→ GET /mcp
→ Server returns 401 Unauthorized
→ WWW-Authenticate header includes OAuth metadata URL
2. Client initiates OAuth flow
→ Opens browser to OIDC provider
→ User logs in
→ Provider redirects with authorization code
2. Claude Code fetches OAuth metadata
→ Discovers Authentik authorization URL
→ Discovers required scopes
3. Client exchanges code for tokens
→ POST to provider token endpoint
→ Receives JWT access token
3. Claude Code initiates OAuth flow
→ Opens browser to Authentik login page
→ User enters credentials
→ Authentik redirects back with authorization code
4. Client reconnects with token
4. Claude Code exchanges code for tokens
→ POST to Authentik token endpoint
→ Receives JWT access token + refresh token
5. Claude Code reconnects with Bearer token
→ POST /mcp with Authorization: Bearer <jwt>
→ Server validates JWT via JWKS
→ Server extracts user + groups
→ RBACMiddleware checks permissions
→ User can invoke allowed tools
→ Server validates JWT via Authentik JWKS
→ Server extracts user identity
→ User can now invoke tools
5. Tool invocation
→ Client: "power on web-server"
→ Middleware: Validate user has POWER_OPS
→ Tool: Execute pyvmomi call
→ Audit: Log with user identity
→ Client: Receive response
6. Tool invocation
→ Client: "power on web-server VM"
→ Server: Validates token, maps user to vCenter creds
→ Server: Executes pyvmomi call
→ Server: Logs "User ryan@example.com powered on web-server"
→ Client: Receives success response
```
---
## Implementation Status
## Implementation Checklist
### Completed
### Phase 1: Prepare Server
- [ ] Add `fastmcp[auth]` to dependencies
- [ ] Create `auth.py` with OIDCProxy configuration
- [ ] Create `credential_broker.py` for user mapping
- [ ] Add audit logging to all tools
- [ ] Update server.py to use HTTP transport
- [x] OIDCProxy configuration (`auth.py`)
- [x] Permission levels and tool mappings (`permissions.py`)
- [x] RBACMiddleware with FastMCP integration (`middleware.py`)
- [x] Audit logging with user context (`audit.py`)
- [x] Server integration with OAuth + RBAC (`server.py`)
- [x] Startup banner showing OAuth/RBAC status
- [x] Security fix: deny-by-default for no groups
- [x] Authentik setup with 5 vsphere-* groups
### Phase 2: Deploy Authentik
- [ ] Docker Compose for Authentik
- [ ] Create OIDC provider and application
- [ ] Configure redirect URIs
- [ ] Note client credentials
- [ ] Test OIDC flow manually with curl
### Future Enhancements
### Phase 3: Integration
- [ ] Configure environment variables
- [ ] Test with `fastmcp dev` (OAuth mode)
- [ ] Test with Claude Code (`claude mcp add --auth oauth`)
- [ ] Verify audit logs show correct user identity
- [ ] Per-user vCenter credential mapping (Vault integration)
- [ ] Rate limiting per user
- [ ] Session management and token refresh
- [ ] Admin tools for permission management
- [ ] Prometheus metrics for RBAC decisions
### Phase 4: Production
- [ ] HTTPS via Caddy reverse proxy
- [ ] Secrets in Docker secrets / Vault
- [ ] Service account with minimal vCenter permissions
- [ ] Log aggregation and monitoring
---
## Security Considerations
## Files to Create/Modify
1. **Default Deny**: Users without recognized groups get NO access
2. **Token Validation**: JWTs validated via OIDC provider's JWKS endpoint
3. **Audit Trail**: All operations logged with user identity
4. **Secrets**: Client secrets should be stored securely (env vars, Docker secrets, Vault)
5. **HTTPS**: Production deployments should use TLS (via Caddy, nginx, etc.)
6. **Service Account**: Use minimal vCenter permissions for the service account
```
esxi-mcp-server/
├── src/esxi_mcp_server/
│ ├── auth.py # NEW: OIDCProxy configuration
│ ├── credential_broker.py # NEW: OAuth → vCenter credential mapping
│ ├── server.py # MODIFY: Add auth, HTTP transport
│ └── mixins/
│ └── *.py # MODIFY: Add ctx.request_context.user logging
├── .env.example # MODIFY: Add OAuth variables
└── docker-compose.yml # MODIFY: Add Authentik services
```
---
## Troubleshooting
## Key Insight
### "401 Unauthorized" on all requests
- Check `OAUTH_ISSUER_URL` points to valid OIDC discovery endpoint
- Verify client ID and secret match provider configuration
- Ensure token hasn't expired
The "middleman" role of the MCP server is critical:
### "Permission denied" errors
- Check user's group memberships in OIDC provider
- Verify groups claim is included in JWT (decode at jwt.io)
- Confirm group names match exactly (e.g., `vsphere-admins` not `vsphere_admins`)
```
OAuth Token (Authentik) ──┐
│
▼
┌─────────────┐
│ MCP Server │ ← Validates OAuth, maps to vCenter creds
│ (Middleman) │ ← Logs audit trail with OAuth identity
└─────────────┘
│
▼
vCenter API (pyvmomi)
```
### Token validation fails
- Ensure OIDC provider issues JWTs (not opaque tokens)
- Check signing key is configured in provider
- Verify `OAUTH_BASE_URL` matches redirect URI in provider
The MCP server doesn't pass OAuth tokens to vCenter. Instead, it:
1. **Authenticates** users via OAuth (trusts Authentik)
2. **Authorizes** by mapping OAuth identity to vCenter credentials
3. **Audits** by logging all actions with the OAuth user identity
4. **Executes** vCenter API calls using mapped credentials
### Audit logs not showing user
- Check `groups` scope is requested
- Verify token contains `preferred_username` or `email` claim
This gives you SSO-like experience while working within vCenter 7.0.3's authentication limitations.

32
README.md
View File

@ -195,41 +195,11 @@ Claude: [snapshots 12 VMs in parallel]
| `VCENTER_CLUSTER` | Target cluster | *auto-detect* |
| `VCENTER_DATASTORE` | Default datastore | *auto-detect* |
| `VCENTER_NETWORK` | Default network | *auto-detect* |
| `MCP_TRANSPORT` | `stdio` or `streamable-http` | `stdio` |
| `MCP_TRANSPORT` | `stdio` or `sse` | `stdio` |
| `LOG_LEVEL` | Logging verbosity | `INFO` |
---
## Multi-User / OAuth Mode
For shared infrastructure or production deployments, mcvsphere supports OAuth 2.1 with any OIDC provider (Authentik, Keycloak, Auth0, etc.):
```bash
# Enable HTTP transport with OAuth
export MCP_TRANSPORT=streamable-http
export OAUTH_ENABLED=true
export OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
export OAUTH_CLIENT_ID=your-client-id
export OAUTH_CLIENT_SECRET=your-client-secret
export OAUTH_BASE_URL=https://mcp.example.com
uvx mcvsphere
```
Users authenticate via browser, and group memberships map to permission levels:
| Group | Access |
|-------|--------|
| `vsphere-super-admins` | Full control (all 94 tools) |
| `vsphere-host-admins` | Host operations + VM management |
| `vsphere-admins` | VM lifecycle management |
| `vsphere-operators` | Power ops + snapshots |
| `vsphere-readers` | Read-only |
See [OAUTH-ARCHITECTURE.md](OAUTH-ARCHITECTURE.md) for detailed setup instructions.
---
## Docker
```bash

80
README_DOCKER.md
View File

@ -235,89 +235,15 @@ MCP_LOG_LEVEL=DEBUG
log_level: "DEBUG"
```
## OAuth Multi-User Mode
For shared infrastructure or production deployments, mcvsphere supports OAuth 2.1 with any OIDC provider. This enables:
- **Browser-based authentication** via Authentik, Keycloak, Auth0, Okta, etc.
- **Group-based RBAC** with 5 permission levels
- **Audit logging** with user identity
### Quick Start (Existing OIDC Provider)
If you already have an OIDC provider:
```bash
# 1. Copy and configure environment
cp .env.oauth.example .env
# Edit .env with your OIDC provider details
# 2. Start mcvsphere with OAuth
docker compose -f docker-compose.oauth-standalone.yml up -d
# 3. Add to Claude Code
claude mcp add -t http vsphere https://mcp.example.com/mcp
```
### Quick Start (New Authentik Deployment)
To deploy mcvsphere with a complete Authentik identity provider:
```bash
# 1. Generate secrets and configure
./scripts/setup-oauth.sh
# 2. Start full stack (mcvsphere + Authentik + PostgreSQL + Redis)
docker compose -f docker-compose.oauth.yml up -d
# 3. Configure Authentik at https://auth.yourdomain.com
# - Create OAuth2 provider
# - Create vsphere-* groups
# - Assign users to groups
```
### RBAC Permission Groups
Create these groups in your OIDC provider:
| Group | Access Level |
|-------|--------------|
| `vsphere-super-admins` | Full control (all 94 tools) |
| `vsphere-host-admins` | Host operations + VM management |
| `vsphere-admins` | VM lifecycle management |
| `vsphere-operators` | Power ops + snapshots |
| `vsphere-readers` | Read-only |
Users without any `vsphere-*` group are denied access (default-deny security).
### Required Environment Variables
```bash
# Transport (must be streamable-http for OAuth)
MCP_TRANSPORT=streamable-http
# OIDC Provider
OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_BASE_URL=https://mcp.example.com
```
See [OAUTH-ARCHITECTURE.md](OAUTH-ARCHITECTURE.md) for detailed setup and troubleshooting.
---
## Production Deployment
### Security Recommendations
1. Use a dedicated service account for vCenter access
2. Enable OAuth authentication (not API keys)
3. Use valid SSL certificates (set `VCENTER_INSECURE=false`)
1. Use a dedicated user account for vCenter access
2. Enable API key authentication
3. Use valid SSL certificates (set `insecure: false`)
4. Limit container resources
5. Use Docker secrets for sensitive data
6. Deploy behind a reverse proxy with HTTPS (Caddy recommended)
### High Availability

64
docker-compose.oauth-standalone.yml
View File

@ -1,64 +0,0 @@
# mcvsphere with OAuth - Standalone Mode
# For users who already have an OIDC provider (Authentik, Keycloak, Auth0, Okta, etc.)
#
# Usage:
# 1. Copy .env.oauth.example to .env
# 2. Configure your OIDC provider settings
# 3. docker compose -f docker-compose.oauth-standalone.yml up -d
#
# Requires:
# - External OIDC provider with OAuth 2.1 support
# - Caddy network (caddy-docker-proxy) for HTTPS termination
#
# For full Authentik deployment, use docker-compose.oauth.yml instead
services:
mcvsphere:
build:
context: .
dockerfile: Dockerfile
image: mcvsphere:${MCVSPHERE_VERSION:-latest}
container_name: mcvsphere
restart: unless-stopped
env_file:
- .env
environment:
# Transport - streamable-http required for OAuth
MCP_TRANSPORT: streamable-http
MCP_HOST: 0.0.0.0
MCP_PORT: 8080
# OAuth - set in .env file
OAUTH_ENABLED: ${OAUTH_ENABLED:-true}
volumes:
- ./logs:/app/logs
networks:
- caddy
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/.well-known/oauth-authorization-server')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
labels:
# Caddy reverse proxy - configure domain in .env
caddy: ${MCP_DOMAIN:-mcp.localhost}
caddy.reverse_proxy: "{{upstreams 8080}}"
# TLS - use 'internal' for local dev, remove for production (auto HTTPS)
caddy.tls: ${MCP_TLS_MODE:-internal}
# WebSocket/streaming support
caddy.reverse_proxy.flush_interval: "-1"
caddy.reverse_proxy.transport: http
caddy.reverse_proxy.transport.read_timeout: "0"
caddy.reverse_proxy.transport.write_timeout: "0"
deploy:
resources:
limits:
memory: 512M
cpus: '1.0'
reservations:
memory: 256M
cpus: '0.25'
networks:
caddy:
external: true

19
docs/.gitignore vendored
View File

@ -1,19 +0,0 @@
# Dependencies
node_modules/
# Build output
dist/
.astro/
# Editor
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Logs
*.log

2
docs/.pnpm-approve-builds
View File

@ -1,2 +0,0 @@
esbuild@*
sharp@*

70
docs/astro.config.mjs
View File

@ -1,70 +0,0 @@
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
// https://astro.build/config
export default defineConfig({
site: 'https://docs.mcvsphere.dev',
telemetry: false,
devToolbar: { enabled: false },
integrations: [
starlight({
title: 'mcvsphere',
description: 'AI-driven VMware vSphere management via Model Context Protocol',
logo: {
src: './src/assets/logo.svg',
replacesTitle: false,
},
social: {
github: 'https://git.supported.systems/MCP/mcvsphere',
},
sidebar: [
{
label: 'Getting Started',
items: [
{ label: 'Introduction', slug: 'getting-started/introduction' },
{ label: 'Installation', slug: 'getting-started/installation' },
{ label: 'Quick Start', slug: 'getting-started/quickstart' },
],
},
{
label: 'Configuration',
items: [
{ label: 'Environment Variables', slug: 'configuration/environment' },
{ label: 'vCenter Connection', slug: 'configuration/vcenter' },
],
},
{
label: 'Deployment',
items: [
{ label: 'Docker Setup', slug: 'deployment/docker' },
{ label: 'OAuth Multi-User', slug: 'deployment/oauth' },
],
},
{
label: 'Reference',
items: [
{ label: 'Tool Reference', slug: 'reference/tools' },
{ label: 'RBAC Permissions', slug: 'reference/rbac' },
{ label: 'Architecture', slug: 'reference/architecture' },
],
},
],
customCss: [
'./src/styles/custom.css',
],
head: [
{
tag: 'meta',
attrs: {
name: 'theme-color',
content: '#146eb4',
},
},
],
editLink: {
baseUrl: 'https://git.supported.systems/MCP/mcvsphere/edit/main/docs/',
},
}),
],
});

15
docs/package.json
View File

@ -1,15 +0,0 @@
{
"name": "mcvsphere-docs",
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"build": "astro build",
"preview": "astro preview"
},
"dependencies": {
"@astrojs/starlight": "^0.32.3",
"astro": "^5.1.6",
"sharp": "^0.33.5"
}
}

4429
docs/pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

4
docs/public/robots.txt
View File

@ -1,4 +0,0 @@
User-agent: *
Allow: /
Sitemap: https://docs.mcvsphere.dev/sitemap-index.xml

22
docs/src/assets/logo.svg
View File

@ -1,22 +0,0 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
<!-- vSphere-inspired cube -->
<defs>
<linearGradient id="grad1" x1="0%" y1="0%" x2="100%" y2="100%">
<stop offset="0%" style="stop-color:#3d9cdb;stop-opacity:1" />
<stop offset="100%" style="stop-color:#146eb4;stop-opacity:1" />
</linearGradient>
<linearGradient id="grad2" x1="0%" y1="100%" x2="100%" y2="0%">
<stop offset="0%" style="stop-color:#0d4f8c;stop-opacity:1" />
<stop offset="100%" style="stop-color:#146eb4;stop-opacity:1" />
</linearGradient>
</defs>
<!-- Main cube shape -->
<path d="M24 4L6 14v20l18 10 18-10V14L24 4z" fill="url(#grad1)" opacity="0.9"/>
<path d="M24 4L6 14l18 10 18-10L24 4z" fill="url(#grad2)" opacity="0.8"/>
<path d="M24 24v20l18-10V14L24 24z" fill="#0d4f8c" opacity="0.7"/>
<path d="M24 24L6 14v20l18 10V24z" fill="#146eb4" opacity="0.6"/>
<!-- VM representation lines -->
<path d="M18 20l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.8"/>
<path d="M18 26l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.6"/>
<path d="M18 32l6-3.5 6 3.5" stroke="#fff" stroke-width="1.5" fill="none" opacity="0.4"/>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 1.2 KiB

6
docs/src/content.config.ts
View File

@ -1,6 +0,0 @@
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
};

141
docs/src/content/docs/configuration/environment.md
View File

@ -1,141 +0,0 @@
---
title: Environment Variables
description: Complete reference for all mcvsphere configuration options
---
import { Aside } from '@astrojs/starlight/components';
## vCenter Connection
These are required to connect to your VMware infrastructure.
| Variable | Description | Default |
|----------|-------------|---------|
| `VCENTER_HOST` | vCenter or ESXi hostname/IP | **required** |
| `VCENTER_USER` | Username (e.g., `admin@vsphere.local`) | **required** |
| `VCENTER_PASSWORD` | Password | **required** |
| `VCENTER_INSECURE` | Skip SSL certificate verification | `false` |
| `VCENTER_DATACENTER` | Target datacenter | auto-detect |
| `VCENTER_CLUSTER` | Target cluster | auto-detect |
| `VCENTER_DATASTORE` | Default datastore | auto-detect |
| `VCENTER_NETWORK` | Default network | auto-detect |
<Aside type="caution">
Only set `VCENTER_INSECURE=true` in development environments. Production deployments should use valid SSL certificates.
</Aside>
## Managing Multiple ESXi Hosts
mcvsphere can manage a list of ESXi hosts and route each tool call to whichever one you choose. Define the list with numbered `ESXI_*` variables:
| Variable | Description |
|----------|-------------|
| `ESXI_HOST` | First host — the **default** used when a call omits `host` |
| `ESXI_USER` / `ESXI_PASS` | Credentials for the default host |
| `ESXI_INSECURE` / `ESXI_NETWORK` | SSL skip / default network for the default host |
| `ESXI_HOST_1`, `ESXI_HOST_2`, … | Additional hosts |
| `ESXI_USER_1` / `ESXI_PASS_1` / … | Per-host credentials (optional) |
| `ESXI_INSECURE_1` / `ESXI_NETWORK_1` / … | Per-host SSL / network (optional) |
A suffixed host that omits its own `USER`/`PASS`/`INSECURE`/`NETWORK` inherits the unsuffixed value, so hosts that share credentials only need a `HOST` line:
```bash
ESXI_HOST=10.0.0.10
ESXI_USER=root
ESXI_PASS=secret
ESXI_NETWORK=VM Network
ESXI_HOST_1=10.0.0.11 # reuses root / secret / VM Network
ESXI_HOST_2=10.0.0.12 # reuses root / secret / VM Network
```
Hosts are identified by their `host` value. Connections are established **lazily** on first use, so an unreachable host never blocks startup or the other hosts.
### Selecting a host per call
Every tool except `list_servers` accepts an optional `host` argument:
```text
list_servers() → list managed hosts + connection status
list_vms(host="10.0.0.11") → VMs on that specific host
get_host_info() → omit host → the default host
create_vm(name="web", host="10.0.0.12")
```
:::note
The host list is produced by a single pluggable function, `load_servers()`. The `ESXI_*` env-var families are the current source; a future HTTP deployment can back it with an API with no tool changes — the per-call `host` selector is stateless by design.
:::
## MCP Transport
Control how mcvsphere communicates with MCP clients.
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_TRANSPORT` | `stdio` or `streamable-http` | `stdio` |
| `MCP_HOST` | HTTP bind address | `0.0.0.0` |
| `MCP_PORT` | HTTP port | `8080` |
### Transport Modes
- **stdio**: Direct subprocess communication. Used for single-user local development.
- **streamable-http**: HTTP server with streaming support. Required for OAuth multi-user deployments.
## OAuth Authentication
Required when `OAUTH_ENABLED=true` for multi-user deployments.
| Variable | Description |
|----------|-------------|
| `OAUTH_ENABLED` | Enable OAuth authentication |
| `OAUTH_ISSUER_URL` | OIDC discovery URL |
| `OAUTH_CLIENT_ID` | OAuth client ID |
| `OAUTH_CLIENT_SECRET` | OAuth client secret |
| `OAUTH_BASE_URL` | Public HTTPS URL for callbacks |
Example OIDC discovery URLs:
- **Authentik**: `https://auth.example.com/application/o/mcvsphere/`
- **Keycloak**: `https://keycloak.example.com/realms/myrealm`
- **Auth0**: `https://myapp.auth0.com/`
- **Okta**: `https://myorg.okta.com/oauth2/default`
## Logging
| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
## Example Configurations
### Local Development
```bash
export VCENTER_HOST=10.20.0.222
export VCENTER_USER=admin@vsphere.local
export VCENTER_PASSWORD=secret
export VCENTER_INSECURE=true
export LOG_LEVEL=DEBUG
```
### Production (Single User)
```bash
export VCENTER_HOST=vcenter.prod.example.com
export VCENTER_USER=svc-mcvsphere@vsphere.local
export VCENTER_PASSWORD="${VCENTER_PASSWORD}" # from secrets manager
export VCENTER_INSECURE=false
```
### Production (Multi-User OAuth)
```bash
export VCENTER_HOST=vcenter.prod.example.com
export VCENTER_USER=svc-mcvsphere@vsphere.local
export VCENTER_PASSWORD="${VCENTER_PASSWORD}"
export MCP_TRANSPORT=streamable-http
export OAUTH_ENABLED=true
export OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
export OAUTH_CLIENT_ID=mcvsphere-client
export OAUTH_CLIENT_SECRET="${OAUTH_CLIENT_SECRET}"
export OAUTH_BASE_URL=https://mcp.example.com
```

126
docs/src/content/docs/configuration/vcenter.md
View File

@ -1,126 +0,0 @@
---
title: vCenter Connection
description: Configuring vCenter/ESXi access for mcvsphere
---
import { Aside, Steps } from '@astrojs/starlight/components';
## Service Account Setup
For production deployments, create a dedicated service account rather than using your personal administrator credentials.
<Steps>
1. **Create the user in vCenter**
In the vSphere Client, go to **Administration** → **Single Sign-On** → **Users and Groups** → **Add User**
- Username: `svc-mcvsphere`
- Domain: `vsphere.local`
- Password: Generate a strong password
2. **Create a role with required permissions**
Go to **Administration** → **Access Control** → **Roles** → **Add Role**
Required permissions vary by which tools you need:
| Permission Category | Required For |
|---------------------|--------------|
| Virtual machine → Interaction | Power operations, console |
| Virtual machine → Inventory | Create, delete, rename VMs |
| Virtual machine → Configuration | CPU, memory, disk changes |
| Virtual machine → Snapshot management | Snapshots |
| Virtual machine → Guest operations | Commands, file transfer |
| Datastore → Browse datastore | OVF deploy, file operations |
| Network → Assign network | Network adapter changes |
| Host → Configuration | Host management tools |
3. **Assign the role**
Go to your datacenter or cluster, **Permissions** tab, **Add Permission**
- User: `svc-mcvsphere@vsphere.local`
- Role: The role you created
- Propagate to children: **Yes**
</Steps>
## Connection Testing
Test your credentials before configuring mcvsphere:
```bash
# Set credentials
export VCENTER_HOST=vcenter.example.com
export VCENTER_USER=svc-mcvsphere@vsphere.local
export VCENTER_PASSWORD=your-password
# Quick test with Python
python -c "
from pyVim.connect import SmartConnect
import ssl
ctx = ssl._create_unverified_context()
si = SmartConnect(host='$VCENTER_HOST', user='$VCENTER_USER', pwd='$VCENTER_PASSWORD', sslContext=ctx)
print(f'Connected to: {si.content.about.fullName}')
"
```
## SSL Certificates
### Self-Signed Certificates (Development)
```bash
export VCENTER_INSECURE=true
```
<Aside type="caution">
This disables SSL verification. Only use in lab environments.
</Aside>
### Custom CA Certificates (Production)
If your vCenter uses certificates signed by an internal CA:
```bash
# Add your CA to the system trust store
sudo cp your-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# Or specify the CA bundle
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
```
## Auto-Detection Behavior
When `VCENTER_DATACENTER`, `VCENTER_CLUSTER`, `VCENTER_DATASTORE`, or `VCENTER_NETWORK` are not set, mcvsphere auto-detects defaults:
1. **Datacenter**: First datacenter found
2. **Cluster**: First cluster in the datacenter
3. **Datastore**: Datastore with most free space
4. **Network**: Network named "VM Network", or first network found
To see what was auto-detected, check the startup logs:
```bash
LOG_LEVEL=DEBUG uvx mcvsphere
```
## Troubleshooting
### "Cannot complete login due to an incorrect user name or password"
- Check username includes domain: `admin@vsphere.local` not `admin`
- Verify password doesn't contain special characters that need escaping
- Confirm the account isn't locked in vCenter
### "SSL: CERTIFICATE_VERIFY_FAILED"
- Use `VCENTER_INSECURE=true` for self-signed certs
- Or install the vCenter CA certificate (see above)
### "Permission denied" for specific operations
- Check the service account has the required vCenter permissions
- Permissions must be assigned at the right level (datacenter, cluster, or VM folder)
- Ensure "Propagate to children" is enabled

186
docs/src/content/docs/deployment/docker.md
View File

@ -1,186 +0,0 @@
---
title: Docker Deployment
description: Run mcvsphere in Docker for production deployments
---
import { Tabs, TabItem, Aside, Steps } from '@astrojs/starlight/components';
## Quick Start
<Steps>
1. **Create configuration**
```bash
# Create environment file
cat > .env << 'EOF'
COMPOSE_PROJECT_NAME=mcvsphere
# vCenter Connection
VCENTER_HOST=vcenter.example.com
VCENTER_USER=svc-mcvsphere@vsphere.local
VCENTER_PASSWORD=your-password
VCENTER_INSECURE=false
# Transport
MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8080
EOF
```
2. **Run the container**
```bash
docker run -d \
--name mcvsphere \
--env-file .env \
-p 8080:8080 \
ghcr.io/supportedsystems/mcvsphere:latest
```
3. **Verify it's running**
```bash
curl http://localhost:8080/.well-known/oauth-authorization-server
```
</Steps>
## Docker Compose
For production deployments, use Docker Compose:
```yaml
# docker-compose.yml
services:
mcvsphere:
image: ghcr.io/supportedsystems/mcvsphere:latest
container_name: mcvsphere
restart: unless-stopped
env_file:
- .env
ports:
- "8080:8080"
volumes:
- ./logs:/app/logs
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/.well-known/oauth-authorization-server')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
deploy:
resources:
limits:
memory: 512M
cpus: '1.0'
reservations:
memory: 256M
cpus: '0.25'
```
```bash
docker compose up -d
docker compose logs -f
```
## With Caddy Reverse Proxy
For HTTPS termination, use [caddy-docker-proxy](https://github.com/lucaslorentz/caddy-docker-proxy):
```yaml
# docker-compose.yml
services:
mcvsphere:
image: ghcr.io/supportedsystems/mcvsphere:latest
restart: unless-stopped
env_file:
- .env
networks:
- caddy
labels:
caddy: mcp.example.com
caddy.reverse_proxy: "{{upstreams 8080}}"
# WebSocket/streaming support
caddy.reverse_proxy.flush_interval: "-1"
caddy.reverse_proxy.transport: http
caddy.reverse_proxy.transport.read_timeout: "0"
caddy.reverse_proxy.transport.write_timeout: "0"
networks:
caddy:
external: true
```
<Aside type="tip">
The `flush_interval` and timeout settings are important for MCP's streaming protocol. Without them, connections may drop unexpectedly.
</Aside>
## Building from Source
```bash
# Clone repository
git clone https://git.supported.systems/MCP/mcvsphere.git
cd mcvsphere
# Build image
docker build -t mcvsphere:local .
# Run
docker run -d --env-file .env mcvsphere:local
```
### Multi-Stage Build
The Dockerfile uses a multi-stage build for minimal image size:
1. **Builder stage**: Installs dependencies with `uv`
2. **Production stage**: Copies only the virtual environment, runs as non-root user
## Health Checks
The container includes automatic health checks that verify the MCP endpoint is responding:
```bash
# Check container health
docker inspect --format='{{.State.Health.Status}}' mcvsphere
# View health check logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' mcvsphere
```
## Logging
Logs are written to `/app/logs` inside the container. Mount a volume to persist them:
```yaml
volumes:
- ./logs:/app/logs
```
View logs:
```bash
# Docker logs
docker logs mcvsphere
# Application logs (if volume mounted)
tail -f ./logs/mcvsphere.log
```
## Resource Limits
Recommended resource limits:
| Setting | Development | Production |
|---------|-------------|------------|
| Memory limit | 256M | 512M |
| Memory reservation | 128M | 256M |
| CPU limit | 0.5 | 1.0 |
| CPU reservation | 0.1 | 0.25 |
## Next Steps
- [OAuth Multi-User Mode](/deployment/oauth/) — Enable authentication for shared deployments
- [RBAC Permissions](/reference/rbac/) — Understand permission levels

259
docs/src/content/docs/deployment/oauth.md
View File

@ -1,259 +0,0 @@
---
title: OAuth Multi-User Mode
description: Enable browser-based authentication with any OIDC provider
---
import { Tabs, TabItem, Aside, Steps, Badge } from '@astrojs/starlight/components';
For shared infrastructure or production deployments, mcvsphere supports OAuth 2.1 with any OIDC-compliant provider. This enables:
- **Browser-based authentication** via Authentik, Keycloak, Auth0, Okta, etc.
- **Group-based RBAC** with 5 permission levels
- **Audit logging** with user identity
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (Claude Code) │
└─────────────────────────────┬───────────────────────────────┘
│ 1. OAuth 2.1 + PKCE flow
│ (browser opens for login)
┌─────────────────────────────▼───────────────────────────────┐
│ OIDC Provider │
│ (Authentik, Keycloak, Auth0, etc.) │
│ - Issues JWT access tokens │
│ - Validates user credentials │
│ - Includes groups claim in token │
└─────────────────────────────┬───────────────────────────────┘
│ 2. JWT Bearer token
┌─────────────────────────────▼───────────────────────────────┐
│ mcvsphere │
│ ┌────────────────────────────────────────────────────┐ │
│ │ OIDCProxy: Validates JWT via JWKS, extracts claims │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ RBACMiddleware: Maps groups → permissions │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ VMware Tools: Execute vCenter operations │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────┘
│ 3. pyvmomi (service account)
┌─────────────────────────────▼───────────────────────────────┐
│ vCenter / ESXi │
└─────────────────────────────────────────────────────────────┘
```
## Quick Start
<Tabs>
<TabItem label="Existing OIDC Provider">
If you already have Authentik, Keycloak, Auth0, or another OIDC provider:
<Steps>
1. **Create OAuth application in your provider**
- Client type: Confidential
- Redirect URI: `https://mcp.example.com/auth/callback`
- Scopes: `openid`, `profile`, `email`, `groups`
2. **Configure environment**
```bash
cat > .env << 'EOF'
# vCenter
VCENTER_HOST=vcenter.example.com
VCENTER_USER=svc-mcvsphere@vsphere.local
VCENTER_PASSWORD=your-password
# Transport (required for OAuth)
MCP_TRANSPORT=streamable-http
MCP_DOMAIN=mcp.example.com
# OAuth
OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_BASE_URL=https://mcp.example.com
EOF
```
3. **Deploy with Docker**
```bash
docker compose -f docker-compose.oauth-standalone.yml up -d
```
4. **Add to Claude Code**
```bash
claude mcp add -t http vsphere https://mcp.example.com/mcp
```
</Steps>
</TabItem>
<TabItem label="New Authentik Setup">
To deploy mcvsphere with a fresh Authentik identity provider:
<Steps>
1. **Generate secrets**
```bash
./scripts/setup-oauth.sh
```
2. **Start full stack**
```bash
docker compose -f docker-compose.oauth.yml up -d
```
This starts:
- mcvsphere (MCP server)
- Authentik (identity provider)
- PostgreSQL (Authentik database)
- Redis (Authentik cache)
3. **Configure Authentik**
Open `https://auth.yourdomain.com` and:
- Create OAuth2 provider for mcvsphere
- Create `vsphere-*` groups
- Assign users to groups
</Steps>
</TabItem>
</Tabs>
## RBAC Permission Groups
Create these groups in your OIDC provider and assign users:
| Group | Access Level |
|-------|--------------|
| `vsphere-super-admins` | Full control (all 94 tools) |
| `vsphere-host-admins` | Host operations + VM management |
| `vsphere-admins` | VM lifecycle management |
| `vsphere-operators` | Power ops + snapshots |
| `vsphere-readers` | Read-only |
<Aside type="caution">
**Default Deny**: Users without any `vsphere-*` group are denied all access. This is a security feature, not a bug.
</Aside>
See [RBAC Permissions Reference](/reference/rbac/) for complete tool-to-permission mappings.
## Authentik Configuration
<Steps>
1. **Create OAuth2/OIDC Provider**
In Authentik, go to **Applications** → **Providers** → **Create**
- Name: `mcvsphere`
- Authorization flow: `default-authorization-flow`
- Client type: **Confidential**
- Client ID: (auto-generated, copy this)
- Client Secret: (auto-generated, copy this)
- Redirect URIs:
```
http://localhost:*/callback
https://mcp.example.com/auth/callback
```
- Signing Key: Select your RS256 certificate
2. **Create Application**
Go to **Applications** → **Applications** → **Create**
- Name: `mcvsphere`
- Slug: `mcvsphere`
- Provider: Select the provider from step 1
3. **Create Groups**
Go to **Directory** → **Groups** → **Create** for each:
- `vsphere-readers`
- `vsphere-operators`
- `vsphere-admins`
- `vsphere-host-admins`
- `vsphere-super-admins`
4. **Assign Users to Groups**
Edit each user and add them to appropriate groups.
</Steps>
## OAuth Flow
When a user connects with Claude Code:
1. **Initial connection** — Client connects without auth, server returns 401 with OAuth metadata URL
2. **Discovery** — Client fetches OIDC configuration from provider
3. **Authorization** — Browser opens, user logs in via OIDC provider
4. **Token exchange** — Authorization code exchanged for JWT access token
5. **Authenticated requests** — Client includes `Authorization: Bearer <jwt>` header
6. **Permission check** — RBACMiddleware validates user's groups against required tool permissions
7. **Audit logging** — Every operation logged with user identity and timing
## Audit Logging
All tool invocations are logged with user context:
```json
{
"timestamp": "2025-01-16T08:15:32.123456+00:00",
"user": "ryan@example.com",
"groups": ["vsphere-admins", "vsphere-operators"],
"tool": "power_on",
"args": {"vm_name": "web-server"},
"duration_ms": 1234.56,
"result": "success"
}
```
Permission denied events:
```json
{
"timestamp": "2025-01-16T08:15:32.123456+00:00",
"user": "guest@example.com",
"groups": ["vsphere-readers"],
"tool": "delete_vm",
"required_permission": "vm_lifecycle",
"event": "PERMISSION_DENIED"
}
```
## Troubleshooting
### "401 Unauthorized" on all requests
- Check `OAUTH_ISSUER_URL` points to valid OIDC discovery endpoint
- Verify client ID and secret match provider configuration
- Ensure token hasn't expired
### "Permission denied" errors
- Check user's group memberships in OIDC provider
- Verify groups claim is included in JWT (decode at [jwt.io](https://jwt.io))
- Confirm group names match exactly: `vsphere-admins` not `vsphere_admins`
### Token validation fails
- Ensure OIDC provider issues JWTs (not opaque tokens)
- Check signing key is configured in provider
- Verify `OAUTH_BASE_URL` matches redirect URI in provider
### User shows as "anonymous"
- Restart Claude Code session after OAuth flow completes
- Check server logs for claims extraction errors
- Verify `groups` scope is included in token request

71
docs/src/content/docs/getting-started/installation.md
View File

@ -1,71 +0,0 @@
---
title: Installation
description: Install mcvsphere in under 30 seconds
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
## Quick Install
<Tabs>
<TabItem label="uvx (Recommended)">
```bash
uvx mcvsphere
```
No installation needed. uvx downloads and runs in one command.
</TabItem>
<TabItem label="pip">
```bash
pip install mcvsphere
```
Then run with:
```bash
mcvsphere
```
</TabItem>
<TabItem label="pipx">
```bash
pipx install mcvsphere
```
Isolated environment, available system-wide.
</TabItem>
</Tabs>
## Requirements
| Requirement | Version |
|------------|---------|
| Python | 3.11+ |
| VMware vSphere | 7.0+ |
| VMware Tools | Latest (for guest operations) |
## Verify Installation
```bash
# Check version
uvx mcvsphere --version
# Or if installed via pip
mcvsphere --version
```
You should see something like:
```
mcvsphere v0.2.3
```
## Dependencies
mcvsphere installs these automatically:
- **[FastMCP](https://gofastmcp.com)** — MCP server framework
- **[pyvmomi](https://github.com/vmware/pyvmomi)** — VMware vSphere Python SDK
- **[pydantic](https://docs.pydantic.dev)** — Configuration validation
## Next Steps
Now that mcvsphere is installed, [configure your vCenter connection](/getting-started/quickstart/).

71
docs/src/content/docs/getting-started/introduction.md
View File

@ -1,71 +0,0 @@
---
title: Introduction
description: What is mcvsphere and why you'd want it
---
mcvsphere is a Model Context Protocol (MCP) server that connects AI assistants like Claude to your VMware vSphere infrastructure. Instead of clicking through the vSphere UI or writing scripts, you can manage your virtual machines through natural language conversation.
## How It Works
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code / MCP Client │
└──────────────────────┬──────────────────────────────────────┘
│ MCP Protocol (stdio or HTTP)
│
┌──────────────────────▼──────────────────────────────────────┐
│ mcvsphere │
│ FastMCP + pyvmomi │
│ │
│ 94 Tools 6 Resources │
│ • VM lifecycle • VMs list │
│ • Power operations • Hosts list │
│ • Snapshots • Datastores │
│ • Guest operations • Networks │
│ • Disk/NIC management • Clusters │
│ • Host management • Resource pools │
└──────────────────────┬──────────────────────────────────────┘
│ pyvmomi (vSphere API)
│
┌──────────────────────▼──────────────────────────────────────┐
│ VMware vCenter / ESXi Host │
└─────────────────────────────────────────────────────────────┘
```
## Two Operating Modes
### STDIO Mode (Single User)
Direct connection for local development or single-user setups. Claude Code spawns the MCP server as a subprocess.
```bash
claude mcp add vsphere "uvx mcvsphere"
```
### HTTP + OAuth Mode (Multi-User)
Browser-based authentication via any OIDC provider. Multiple users share one server, each with their own permissions based on group membership.
```bash
claude mcp add -t http vsphere https://mcp.example.com/mcp
```
## What Can You Do?
With mcvsphere connected, you can ask Claude to:
- **Create infrastructure**: "Spin up 3 Ubuntu VMs with 4 CPUs each"
- **Manage power**: "Power on all VMs starting with 'prod-'"
- **Take snapshots**: "Snapshot all production VMs before the update"
- **Run commands**: "Check the disk usage on linux-server" (no SSH needed)
- **Configure hardware**: "Add a 100GB disk to the database server"
- **Deploy appliances**: "Deploy this OVA to the dev cluster"
- **Monitor systems**: "Show me which hosts have high memory usage"
All 94 tools work through conversation. No scripting required.
## Next Steps
- [Install mcvsphere](/getting-started/installation/)
- [Configure vCenter connection](/getting-started/quickstart/)
- [Learn about all 94 tools](/reference/tools/)

102
docs/src/content/docs/getting-started/quickstart.md
View File

@ -1,102 +0,0 @@
---
title: Quick Start
description: Connect mcvsphere to vCenter and Claude Code in 2 minutes
---
import { Steps, Aside } from '@astrojs/starlight/components';
## Single-User Setup (STDIO)
<Steps>
1. **Set your vCenter credentials**
```bash
export VCENTER_HOST=vcenter.example.com
export VCENTER_USER=administrator@vsphere.local
export VCENTER_PASSWORD=your-password
```
<Aside type="tip">
For self-signed certificates in dev/lab environments:
```bash
export VCENTER_INSECURE=true
```
</Aside>
2. **Add to Claude Code**
```bash
claude mcp add vsphere "uvx mcvsphere"
```
3. **Test the connection**
Open Claude Code and ask:
```
List all VMs in my vCenter
```
Claude should respond with your VM inventory.
</Steps>
## Multi-User Setup (HTTP + OAuth)
For shared infrastructure with multiple users, see [OAuth Multi-User Deployment](/deployment/oauth/).
## Example Conversations
Once connected, try these:
### Create a VM
```
Create a VM called "test-web" with 4 CPUs, 8GB RAM, and 100GB disk
```
### Manage Snapshots
```
Take a snapshot of production-db called "before-upgrade"
```
### Run Commands in Guests
```
What's the uptime on linux-server?
```
mcvsphere runs `uptime` inside the VM via VMware Tools—no SSH required.
### Take Console Screenshots
```
Show me what's on the screen of that stuck VM
```
## Troubleshooting
### "Failed to connect to vCenter"
- Verify `VCENTER_HOST` is reachable: `nc -zv $VCENTER_HOST 443`
- Check username format: `admin@vsphere.local` not just `admin`
- Try `VCENTER_INSECURE=true` for certificate issues
### "VMware Tools not running"
Guest operations require VMware Tools installed and running in the VM:
```
Check VMware Tools status on linux-server
```
### "Permission denied"
Your vCenter user needs appropriate permissions. For testing, use an administrator account. For production, create a dedicated service account with minimal required permissions.
## Next Steps
- [Environment Variables Reference](/configuration/environment/)
- [Docker Deployment](/deployment/docker/)
- [All 94 Tools](/reference/tools/)

81
docs/src/content/docs/index.mdx
View File

@ -1,81 +0,0 @@
---
title: mcvsphere
description: 94 tools. Full VMware control. Natural language.
template: splash
hero:
tagline: Stop clicking through vSphere. Start talking to it.
image:
file: ../../assets/logo.svg
actions:
- text: Get Started
link: /getting-started/installation/
icon: right-arrow
- text: View on GitHub
link: https://git.supported.systems/MCP/mcvsphere
icon: external
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## What is mcvsphere?
mcvsphere is an MCP server that gives AI assistants like Claude complete control over your VMware infrastructure. Create VMs, manage snapshots, run commands inside guests, take console screenshots, configure network appliances—all through conversation.
**94 MCP tools.** Not a toy demo. Not "just the basics." The whole thing.
```
You: "Spin up a new VM with 4 CPUs and 16GB RAM, clone it twice,
then snapshot all three before I start testing"
Claude: Done. Three VMs running, all snapshotted. What's next?
```
## Key Features
<CardGrid stagger>
<Card title="94 MCP Tools" icon="rocket">
VM lifecycle, power operations, snapshots, guest operations, serial console, disk management, network adapters, OVF/OVA, host management, and more.
</Card>
<Card title="Guest Operations" icon="seti:shell">
Run commands inside VMs, transfer files, browse filesystems—no SSH required. VMware Tools does the heavy lifting.
</Card>
<Card title="OAuth + RBAC" icon="shield">
Multi-user authentication via any OIDC provider with 5 permission levels. Audit logging shows WHO did WHAT.
</Card>
<Card title="Real-time Resources" icon="list-format">
6 MCP resources provide always-current data: VMs, hosts, datastores, networks, clusters, resource pools.
</Card>
</CardGrid>
## Quick Example
```bash
# Install
uvx mcvsphere
# Configure
export VCENTER_HOST=vcenter.example.com
export VCENTER_USER=administrator@vsphere.local
export VCENTER_PASSWORD=your-password
# Add to Claude Code
claude mcp add vsphere "uvx mcvsphere"
```
That's it. You're managing vSphere with AI now.
## Requirements
- Python 3.11+
- VMware vSphere 7.0+ (ESXi or vCenter)
- VMware Tools (for guest operations)
## Built With
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP server framework
- [pyVmomi](https://github.com/vmware/pyvmomi) — VMware vSphere API
---
**94 tools. Your entire VMware infrastructure. Controlled by conversation.**

239
docs/src/content/docs/reference/architecture.md
View File

@ -1,239 +0,0 @@
---
title: Architecture
description: Technical overview of mcvsphere internals
---
import { Aside } from '@astrojs/starlight/components';
## System Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (Claude Code) │
└──────────────────────────┬──────────────────────────────────┘
│
│ MCP Protocol
│ (stdio or streamable-http)
│
┌──────────────────────────▼──────────────────────────────────┐
│ mcvsphere │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ FastMCP │ │
│ │ - Protocol handling (JSON-RPC 2.0) │ │
│ │ - Tool registration and dispatch │ │
│ │ - Resource serving │ │
│ │ - OAuth integration (OIDCProxy) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ RBACMiddleware │ │
│ │ - Intercepts all tool calls │ │
│ │ - Extracts user from OAuth token │ │
│ │ - Enforces permission checks │ │
│ │ - Audit logging │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Tool Implementations │ │
│ │ - vm_lifecycle.py (7 tools) │ │
│ │ - power_ops.py (6 tools) │ │
│ │ - snapshots.py (5 tools) │ │
│ │ - guest_ops.py (7 tools) │ │
│ │ - ... (94 tools total) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Connection Manager │ │
│ │ - pyvmomi ServiceInstance │ │
│ │ - Connection pooling │ │
│ │ - Reconnection handling │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│
│ vSphere API (SOAP/REST)
│
┌──────────────────────────▼──────────────────────────────────┐
│ VMware vCenter / ESXi │
└─────────────────────────────────────────────────────────────┘
```
## Source Layout
```
src/mcvsphere/
├── __init__.py # Package entry point, version
├── server.py # FastMCP server setup
├── config.py # Pydantic Settings configuration
├── connection.py # vSphere connection manager
├── auth.py # OIDCProxy configuration
├── middleware.py # RBAC middleware
├── permissions.py # Permission levels and mappings
├── audit.py # Audit logging
└── tools/ # MCP tool implementations
├── __init__.py
├── vm_lifecycle.py
├── power_ops.py
├── snapshots.py
├── guest_ops.py
├── serial_console.py
├── disk_mgmt.py
├── nic_mgmt.py
├── ovf_ops.py
├── host_mgmt.py
├── datastore_ops.py
└── vcenter_ops.py
```
## Key Components
### FastMCP Server (`server.py`)
The core MCP server built on [FastMCP](https://gofastmcp.com):
```python
from fastmcp import FastMCP
mcp = FastMCP(
name="mcvsphere",
instructions="VMware vSphere management server..."
)
# Tools are registered via decorators
@mcp.tool()
def list_vms() -> list[dict]:
"""List all virtual machines."""
return connection.list_vms()
```
### Configuration (`config.py`)
Pydantic Settings model for type-safe configuration:
```python
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
vcenter_host: str
vcenter_user: str
vcenter_password: str
vcenter_insecure: bool = False
mcp_transport: Literal["stdio", "streamable-http"] = "stdio"
oauth_enabled: bool = False
# ...
```
### Connection Manager (`connection.py`)
Manages the pyvmomi ServiceInstance connection:
```python
class VSphereConnection:
def __init__(self, settings: Settings):
self.si = SmartConnect(
host=settings.vcenter_host,
user=settings.vcenter_user,
pwd=settings.vcenter_password,
sslContext=self._get_ssl_context()
)
def list_vms(self) -> list[dict]:
content = self.si.RetrieveContent()
# ... pyvmomi operations
```
### RBAC Middleware (`middleware.py`)
Intercepts all tool calls for permission checking:
```python
from fastmcp import Middleware
class RBACMiddleware(Middleware):
async def on_call_tool(self, context, call_next):
# 1. Extract user from OAuth token
claims = self._extract_user_from_context(context.fastmcp_context)
groups = claims.get("groups", [])
# 2. Check permission
tool_name = context.message.name
if not check_permission(tool_name, groups):
raise PermissionDeniedError(...)
# 3. Execute with audit logging
result = await call_next(context)
audit_log(tool_name, claims, result)
return result
```
### OAuth Configuration (`auth.py`)
Configures FastMCP's OIDCProxy for token validation:
```python
from fastmcp.server.auth import OIDCProxy
def create_auth_provider(settings: Settings) -> OIDCProxy | None:
if not settings.oauth_enabled:
return None
return OIDCProxy(
issuer_url=settings.oauth_issuer_url,
client_id=settings.oauth_client_id,
client_secret=settings.oauth_client_secret,
redirect_uri=f"{settings.oauth_base_url}/auth/callback",
required_scopes=[], # Authentik uses opaque tokens
)
```
## Data Flow
### Tool Invocation (STDIO mode)
1. Claude Code sends JSON-RPC request via stdin
2. FastMCP parses and validates request
3. Tool function executes
4. pyvmomi calls vSphere API
5. Result serialized and returned via stdout
### Tool Invocation (HTTP + OAuth mode)
1. Client sends HTTP POST with Bearer token
2. OIDCProxy validates JWT via JWKS
3. RBACMiddleware extracts claims, checks permissions
4. Tool function executes
5. Audit log written
6. Result returned as HTTP response
## Performance Considerations
### Connection Reuse
A single pyvmomi connection is shared across all requests. This avoids the overhead of establishing new connections for each tool call.
### Lazy Loading
vCenter inventory is fetched on-demand rather than cached. This ensures data freshness but means each tool call queries vCenter directly.
### Resource Pooling
For high-volume deployments, consider running multiple mcvsphere instances behind a load balancer. Each instance maintains its own vCenter connection.
## Security Model
### STDIO Mode
- No authentication (trusts the parent process)
- Single-user by design
- Credentials passed via environment variables
### HTTP + OAuth Mode
- JWT validation via OIDC provider
- Group-based RBAC
- Audit trail with user identity
- Service account connection to vCenter (user identity tracked in audit logs, not vCenter permissions)
<Aside>
In OAuth mode, ALL users share the same vCenter service account. User identity is tracked in mcvsphere audit logs, not vCenter audit logs. Future versions may support per-user vCenter credentials via Vault integration.
</Aside>

184
docs/src/content/docs/reference/rbac.md
View File

@ -1,184 +0,0 @@
---
title: RBAC Permissions
description: Role-based access control for multi-user deployments
---
import { Aside } from '@astrojs/starlight/components';
When OAuth is enabled, mcvsphere enforces role-based access control (RBAC) based on the user's OAuth group memberships.
## Permission Levels
mcvsphere defines 5 permission levels, from least to most privileged:
| Level | Description | Tools |
|-------|-------------|-------|
| `READ_ONLY` | View-only operations | 32 tools |
| `POWER_OPS` | Power and snapshot operations | 14 tools |
| `VM_LIFECYCLE` | Create/delete/modify VMs | 33 tools |
| `HOST_ADMIN` | ESXi host operations | 6 tools |
| `FULL_ADMIN` | Everything including guest OS | 11 tools |
## OAuth Groups
Map OAuth groups to permission levels:
| OAuth Group | Permissions Granted |
|-------------|---------------------|
| `vsphere-readers` | READ_ONLY |
| `vsphere-operators` | READ_ONLY + POWER_OPS |
| `vsphere-admins` | READ_ONLY + POWER_OPS + VM_LIFECYCLE |
| `vsphere-host-admins` | READ_ONLY + POWER_OPS + VM_LIFECYCLE + HOST_ADMIN |
| `vsphere-super-admins` | ALL (full access) |
<Aside type="caution">
**Default Deny Security**: Users with NO recognized `vsphere-*` groups are denied ALL access. There is no implicit "read" permission.
</Aside>
## Tool Permission Mapping
### READ_ONLY (32 tools)
View and inspect operations:
```
list_vms, get_vm_info, list_snapshots, get_vm_stats
get_host_stats, vm_screenshot, get_vm_tools_status
wait_for_vm_tools, list_disks, get_disk_info
list_nics, get_nic_info, get_serial_port
list_hosts, get_host_info, get_host_hardware
get_host_networking, list_services, get_service_status
get_ntp_config, get_datastore_info, browse_datastore
get_vcenter_info, get_resource_pool_info, get_network_info
list_templates, get_alarms, get_recent_events
list_folders, list_clusters, get_cluster_info
list_resource_pools, list_tags, get_vm_tags
list_recent_tasks, list_recent_events
```
### POWER_OPS (14 tools)
Power state and snapshots:
```
power_on_vm, power_off_vm, shutdown_guest
reboot_guest, suspend_vm, reset_vm
create_snapshot, revert_to_snapshot
delete_snapshot, delete_all_snapshots
connect_nic, setup_serial_port
connect_serial_port, clear_serial_port
```
### VM_LIFECYCLE (33 tools)
Create, modify, and delete VMs:
```
create_vm, clone_vm, delete_vm
reconfigure_vm, rename_vm
add_disk, remove_disk, resize_disk
add_nic, remove_nic, change_nic_network
remove_serial_port
deploy_ovf, export_ovf, list_ovf_networks
upload_to_datastore, download_from_datastore
create_folder, delete_folder, move_vm_to_folder
create_resource_pool, delete_resource_pool
move_vm_to_resource_pool
apply_tag_to_vm, remove_tag_from_vm
migrate_vm, cancel_task
```
### HOST_ADMIN (6 tools)
ESXi host management:
```
start_service, stop_service, restart_service
enter_maintenance_mode, exit_maintenance_mode
reboot_host, shutdown_host
```
### FULL_ADMIN (11 tools)
Guest OS operations and full control:
```
run_command_in_guest, read_guest_file, write_guest_file
list_guest_processes, list_guest_directory
create_guest_directory, delete_guest_file
```
<Aside>
Guest operations are the most privileged because they allow arbitrary command execution inside VMs.
</Aside>
## Permission Check Flow
When a tool is invoked:
1. **Extract user identity** from OAuth token claims
2. **Get user's groups** from `groups` claim
3. **Look up required permission** for the tool
4. **Check if any group grants** the required permission
5. **Allow or deny** with audit logging
```python
# Pseudocode
def check_permission(tool_name: str, user_groups: list[str]) -> bool:
required = TOOL_PERMISSIONS[tool_name] # e.g., POWER_OPS
for group in user_groups:
if group in GROUP_PERMISSIONS:
granted = GROUP_PERMISSIONS[group] # e.g., {READ_ONLY, POWER_OPS}
if required in granted:
return True
return False # Default deny
```
## Audit Logging
Every permission decision is logged:
### Successful access
```json
{
"timestamp": "2025-01-16T08:15:32.123456+00:00",
"user": "ryan@example.com",
"groups": ["vsphere-admins"],
"tool": "power_on_vm",
"args": {"vm_name": "web-server"},
"duration_ms": 1234.56,
"result": "success"
}
```
### Permission denied
```json
{
"timestamp": "2025-01-16T08:15:32.123456+00:00",
"user": "intern@example.com",
"groups": ["vsphere-readers"],
"tool": "delete_vm",
"args": {"vm_name": "production-db"},
"required_permission": "vm_lifecycle",
"event": "PERMISSION_DENIED"
}
```
## Troubleshooting
### "Permission denied" for expected access
1. **Check group names match exactly**: `vsphere-admins` vs `vsphere_admins`
2. **Verify groups claim** in JWT token (decode at [jwt.io](https://jwt.io))
3. **Check group membership** in your OIDC provider
4. **Review audit logs** for the exact permission required
### User has no permissions at all
1. **Confirm user is in at least one** `vsphere-*` group
2. **Check OIDC provider** includes `groups` in token claims
3. **Verify** the groups scope is requested during OAuth flow

202
docs/src/content/docs/reference/tools.md
View File

@ -1,202 +0,0 @@
---
title: Tool Reference
description: Complete reference for all 94 MCP tools
---
import { Aside } from '@astrojs/starlight/components';
mcvsphere provides 94 MCP tools for comprehensive VMware vSphere management.
## VM Lifecycle
Create, clone, delete, and configure virtual machines.
| Tool | Description |
|------|-------------|
| `create_vm` | Create a new VM from scratch |
| `clone_vm` | Clone from template or existing VM |
| `delete_vm` | Remove a VM permanently |
| `reconfigure_vm` | Change CPU, memory, annotations |
| `rename_vm` | Rename a VM |
| `list_vms` | List all VMs |
| `get_vm_info` | Detailed VM information |
## Power Operations
Control VM power state.
| Tool | Description |
|------|-------------|
| `power_on_vm` | Start a VM |
| `power_off_vm` | Force power off (like pulling the plug) |
| `shutdown_guest` | Graceful OS shutdown via VMware Tools |
| `reboot_guest` | Graceful OS reboot via VMware Tools |
| `suspend_vm` | Suspend to memory |
| `reset_vm` | Hard reset |
<Aside type="tip">
Use `shutdown_guest` and `reboot_guest` for graceful operations. They require VMware Tools running in the guest.
</Aside>
## Snapshots
Point-in-time VM state management.
| Tool | Description |
|------|-------------|
| `create_snapshot` | Create a new snapshot |
| `revert_to_snapshot` | Restore VM to snapshot state |
| `delete_snapshot` | Remove a specific snapshot |
| `delete_all_snapshots` | Remove all snapshots (consolidate) |
| `list_snapshots` | List all snapshots |
## Guest Operations
Execute commands and transfer files inside VMs without SSH.
| Tool | Description |
|------|-------------|
| `run_command_in_guest` | Execute any command in the guest OS |
| `read_guest_file` | Download file from guest |
| `write_guest_file` | Upload file to guest |
| `list_guest_processes` | List running processes |
| `list_guest_directory` | Browse guest filesystem |
| `create_guest_directory` | Create directory in guest |
| `delete_guest_file` | Delete file in guest |
<Aside type="note">
Guest operations require VMware Tools installed and running. Use `get_vm_tools_status` to verify.
</Aside>
## Console & Monitoring
Visual access and performance monitoring.
| Tool | Description |
|------|-------------|
| `vm_screenshot` | Capture VM console as image |
| `get_vm_stats` | CPU, memory, disk, network metrics |
| `get_host_stats` | ESXi host performance metrics |
| `wait_for_vm_tools` | Block until Tools are ready |
| `get_vm_tools_status` | Check Tools installation state |
## Serial Console
For network appliances and headless systems.
| Tool | Description |
|------|-------------|
| `setup_serial_port` | Configure serial port |
| `get_serial_port` | Get serial port configuration |
| `connect_serial_port` | Get connection URI (telnet/ssh) |
| `clear_serial_port` | Clear serial port buffer |
| `remove_serial_port` | Remove serial port |
## Disk Management
Virtual disk operations.
| Tool | Description |
|------|-------------|
| `add_disk` | Add new virtual disk |
| `remove_disk` | Remove virtual disk |
| `resize_disk` | Expand disk capacity |
| `list_disks` | List all disks |
| `get_disk_info` | Detailed disk information |
## Network Adapters
Virtual NIC management.
| Tool | Description |
|------|-------------|
| `add_nic` | Add network adapter |
| `remove_nic` | Remove network adapter |
| `connect_nic` | Connect/disconnect NIC |
| `change_nic_network` | Change port group |
| `list_nics` | List all NICs |
| `get_nic_info` | Detailed NIC information |
## OVF/OVA Operations
Deploy and export virtual appliances.
| Tool | Description |
|------|-------------|
| `deploy_ovf` | Deploy OVF/OVA package |
| `export_ovf` | Export VM as OVF |
| `list_ovf_networks` | List networks in OVF |
| `upload_to_datastore` | Upload file to datastore |
| `download_from_datastore` | Download file from datastore |
## Host Management
ESXi host operations.
| Tool | Description |
|------|-------------|
| `list_hosts` | List all ESXi hosts |
| `get_host_info` | Host configuration details |
| `get_host_hardware` | Hardware inventory |
| `get_host_networking` | Network configuration |
| `list_services` | Host services |
| `get_service_status` | Service state |
| `start_service` | Start a host service |
| `stop_service` | Stop a host service |
| `restart_service` | Restart a host service |
| `get_ntp_config` | NTP configuration |
## Datastore & Resources
Storage and resource inventory.
| Tool | Description |
|------|-------------|
| `get_datastore_info` | Datastore capacity and usage |
| `browse_datastore` | List datastore contents |
| `get_vcenter_info` | vCenter version and configuration |
| `get_resource_pool_info` | Resource pool settings |
| `get_network_info` | Network/port group details |
| `list_templates` | VM templates |
| `get_alarms` | Active alarms |
| `get_recent_events` | Recent vCenter events |
## vCenter Operations
Organization and cluster management.
| Tool | Description |
|------|-------------|
| `list_folders` | VM and host folders |
| `create_folder` | Create new folder |
| `delete_folder` | Remove folder |
| `move_vm_to_folder` | Organize VMs |
| `list_clusters` | Compute clusters |
| `get_cluster_info` | Cluster configuration |
| `list_resource_pools` | Resource pools |
| `create_resource_pool` | Create resource pool |
| `delete_resource_pool` | Remove resource pool |
| `move_vm_to_resource_pool` | Move VM to pool |
| `list_tags` | vCenter tags |
| `get_vm_tags` | Tags on a VM |
| `apply_tag_to_vm` | Apply tag |
| `remove_tag_from_vm` | Remove tag |
| `migrate_vm` | vMotion/Storage vMotion |
| `list_recent_tasks` | Recent vCenter tasks |
| `list_recent_events` | Recent events |
| `cancel_task` | Cancel running task |
## MCP Resources
In addition to tools, mcvsphere provides 6 real-time resources:
| Resource URI | Data |
|--------------|------|
| `esxi://vms` | All virtual machines |
| `esxi://hosts` | All ESXi hosts |
| `esxi://datastores` | All datastores |
| `esxi://networks` | All networks |
| `esxi://clusters` | All clusters |
| `esxi://resource-pools` | All resource pools |
Resources provide always-current inventory data that Claude can reference during conversations.

74
docs/src/styles/custom.css
View File

@ -1,74 +0,0 @@
/* mcvsphere Documentation Custom Styles */
:root {
/* VMware-inspired color palette */
--sl-color-accent-low: #1a3a5c;
--sl-color-accent: #146eb4;
--sl-color-accent-high: #3d9cdb;
--sl-color-white: #ffffff;
--sl-color-gray-1: #eceef2;
--sl-color-gray-2: #c0c2c7;
--sl-color-gray-3: #888b96;
--sl-color-gray-4: #545861;
--sl-color-gray-5: #353841;
--sl-color-gray-6: #24272f;
--sl-color-black: #17181c;
}
:root[data-theme='dark'] {
--sl-color-accent-low: #1a3a5c;
--sl-color-accent: #3d9cdb;
--sl-color-accent-high: #7fbfeb;
}
/* Code block styling */
.expressive-code {
margin: 1.5rem 0;
}
/* Hero section enhancement */
.hero {
--sl-color-hero-text: var(--sl-color-white);
}
/* Card styling for feature boxes */
.card {
border-radius: 0.5rem;
background: var(--sl-color-gray-6);
padding: 1.5rem;
margin: 1rem 0;
}
/* Badge styling for permission levels */
.badge {
display: inline-block;
padding: 0.25rem 0.5rem;
border-radius: 0.25rem;
font-size: 0.875rem;
font-weight: 500;
}
.badge-reader {
background: #e3f2fd;
color: #1565c0;
}
.badge-operator {
background: #e8f5e9;
color: #2e7d32;
}
.badge-admin {
background: #fff3e0;
color: #ef6c00;
}
.badge-host-admin {
background: #fce4ec;
color: #c2185b;
}
.badge-super-admin {
background: #f3e5f5;
color: #7b1fa2;
}

6
docs/tsconfig.json
View File

@ -1,6 +0,0 @@
{
"extends": "astro/tsconfigs/strict",
"compilerOptions": {
"strictNullChecks": true
}
}

2
pyproject.toml
View File

@ -1,6 +1,6 @@
[project]
name = "mcvsphere"
version = "0.2.3"
version = "0.2.1"
description = "Model Control for vSphere - AI-driven VMware virtual machine management via MCP"
readme = "README.md"
license = "MIT"

68
scripts/esxi-ssh.sh
View File

@ -1,68 +0,0 @@
#!/usr/bin/env bash
# esxi-ssh.sh — on-demand ESXi SSH toggle via the vSphere API (govc + .env creds)
#
# The API account in .env (ESXI_USER, e.g. "claude") can toggle the TSM-SSH
# service but has no interactive host shell, so the `shell` subcommand logs in
# as root by default. Override the shell login with ESXI_SSH_USER.
#
# Usage:
# ./esxi-ssh.sh status # show current TSM-SSH state
# ./esxi-ssh.sh on # enable + start SSH (persists across reboot)
# ./esxi-ssh.sh off # stop + disable SSH (secure default)
# ./esxi-ssh.sh shell [cmd...] # start SSH, log in (root), restore prior state on exit
#
# Env overrides: ENV_FILE (default ../.env), ESXI_SSH_USER (default root)
set -euo pipefail
ENV_FILE="${ENV_FILE:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.env}"
[[ -r "$ENV_FILE" ]] || { echo "esxi-ssh: env file not readable: $ENV_FILE" >&2; exit 1; }
getenv() { grep -E "^$1=" "$ENV_FILE" | head -1 | cut -d= -f2-; }
HOST="$(getenv ESXI_HOST)"
export GOVC_URL="https://${HOST}"
export GOVC_USERNAME="$(getenv ESXI_USER)"
export GOVC_PASSWORD="$(getenv ESXI_PASS)"
export GOVC_INSECURE=1
SSH_USER="${ESXI_SSH_USER:-root}"
# Prints the TSM-SSH row's "policy status" (e.g. "off Running" / "on Stopped")
ssh_state() { govc host.service.ls 2>/dev/null | awk '/^TSM-SSH[[:space:]]/{print $2, $3}'; }
status() { govc host.service.ls | awk 'NR==1 || /^TSM-SSH[[:space:]]/'; }
on() {
govc host.service enable TSM-SSH >/dev/null 2>&1 || true
govc host.service start TSM-SSH >/dev/null 2>&1 || true
echo "esxi-ssh: SSH enabled on ${HOST}"
status
}
off() {
govc host.service stop TSM-SSH >/dev/null 2>&1 || true
govc host.service disable TSM-SSH >/dev/null 2>&1 || true
echo "esxi-ssh: SSH disabled on ${HOST}"
status
}
shell() {
read -r _ prev_status < <(ssh_state)
echo "esxi-ssh: prior TSM-SSH status=${prev_status:-unknown}"
govc host.service start TSM-SSH >/dev/null 2>&1 || true
# Leave it as we found it: only stop SSH on exit if it was NOT already running
if [[ "${prev_status:-}" != "Running" ]]; then
trap 'echo "esxi-ssh: restoring SSH to stopped"; govc host.service stop TSM-SSH >/dev/null 2>&1 || true' EXIT
fi
echo "esxi-ssh: connecting as ${SSH_USER}@${HOST} ..."
ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "${SSH_USER}@${HOST}" "$@"
}
case "${1:-status}" in
on) on ;;
off) off ;;
status) status ;;
shell) shift; shell "$@" ;;
*) echo "usage: $(basename "$0") {on|off|status|shell [cmd...]}" >&2; exit 1 ;;
esac

20
src/mcvsphere/connection.py
View File

@ -61,26 +61,6 @@ class VMwareConnection:
self._setup_datastore()
self._setup_network()
def ensure_connected(self) -> None:
"""Reconnect if the cached session has expired server-side.
ESXi expires idle SOAP sessions; the cached ``ServiceInstance`` then
raises ``NotAuthenticated`` on the next call. Probing ``currentSession``
is one cheap round-trip — None or a raised fault both mean "dead", so
we rebuild the connection (and re-resolve datacenter/datastore/etc).
"""
try:
if (
self.si is not None
and self.content is not None
and self.content.sessionManager.currentSession is not None
):
return # session is alive
except Exception:
pass # any fault here means the session is unusable
logger.info("vSphere session expired; reconnecting to %s", self.settings.vcenter_host)
self._connect()
def _setup_datacenter(self) -> None:
"""Find and configure the target datacenter."""
datacenters = [

76
src/mcvsphere/connection_manager.py
View File

@ -1,76 +0,0 @@
"""Manages VMware connections to multiple ESXi hosts, keyed by host.
Connections are established lazily on first use so one unreachable host does
not block startup or the other hosts. Tools select a host per call via the
``host`` argument; omitting it uses the default (first) server.
"""
import logging
from typing import TYPE_CHECKING, Any
from mcvsphere.connection import VMwareConnection
if TYPE_CHECKING:
from mcvsphere.config import Settings
from mcvsphere.servers import ServerConfig
logger = logging.getLogger(__name__)
class ConnectionManager:
"""Holds the managed server inventory and their lazy connections."""
def __init__(self, servers: list["ServerConfig"], settings: "Settings"):
if not servers:
raise ValueError("No ESXi servers configured (set ESXI_HOST[_N] vars)")
self._servers: dict[str, ServerConfig] = {s.host: s for s in servers}
self._default_host: str = servers[0].host
self._settings = settings
self._connections: dict[str, VMwareConnection] = {}
@property
def hosts(self) -> list[str]:
"""All managed host identifiers."""
return list(self._servers)
@property
def default_host(self) -> str:
return self._default_host
def get(self, host: str | None = None) -> VMwareConnection:
"""Return the connection for ``host`` (default if None), connecting lazily."""
target = host or self._default_host
if target not in self._servers:
known = ", ".join(self._servers) or "(none)"
raise ValueError(f"Unknown server '{target}'. Managed hosts: {known}")
if target not in self._connections:
logger.info("Connecting to ESXi host %s", target)
self._connections[target] = VMwareConnection(
self._servers[target].to_settings(self._settings)
)
else:
# Cached connection may have a server-expired session; revive it.
self._connections[target].ensure_connected()
return self._connections[target]
def describe(self) -> list[dict[str, Any]]:
"""Read-only summary of managed servers (no connection attempts)."""
return [
{
"host": host,
"user": cfg.user,
"network": cfg.network,
"insecure": cfg.insecure,
"default": host == self._default_host,
"connected": host in self._connections,
}
for host, cfg in self._servers.items()
]
def disconnect_all(self) -> None:
for conn in self._connections.values():
try:
conn.disconnect()
except Exception:
logger.warning("Error disconnecting", exc_info=True)
self._connections.clear()

190
src/mcvsphere/middleware.py
View File

@ -3,18 +3,12 @@
Provides decorators and hooks for wrapping tool execution with:
- OAuth permission validation
- Audit logging with user identity
- FastMCP middleware integration for RBAC
"""
import logging
import time
from collections.abc import Callable
from functools import wraps
from typing import TYPE_CHECKING, Any
import mcp.types as mt
from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from fastmcp.tools.tool import ToolResult
from typing import Any
from mcvsphere.audit import (
audit_log,
@ -30,11 +24,6 @@ from mcvsphere.permissions import (
get_required_permission,
)
if TYPE_CHECKING:
from fastmcp.server.context import Context
logger = logging.getLogger(__name__)
def with_permission_check(tool_name: str) -> Callable:
"""Decorator factory for permission checking and audit logging.
@ -92,26 +81,24 @@ def with_permission_check(tool_name: str) -> Callable:
def extract_user_from_context(ctx) -> dict[str, Any] | None:
"""Extract user information from FastMCP context.
Uses FastMCP's dependency injection to get the access token from
the current request's context variable.
Args:
ctx: FastMCP Context object (unused, kept for API compatibility).
ctx: FastMCP Context object.
Returns:
User info dict from OAuth token claims, or None if not authenticated.
"""
try:
# FastMCP stores access token in a context variable, accessed via dependency
from fastmcp.server.dependencies import get_access_token
if ctx is None:
return None
access_token = get_access_token()
if access_token and hasattr(access_token, "claims"):
return access_token.claims
except (RuntimeError, ImportError) as e:
# RuntimeError: No active HTTP request context
# ImportError: FastMCP auth dependencies not available
logger.debug("Could not get access token: %s", e)
# Try to get access token from context
try:
# FastMCP stores the access token in request_context
if hasattr(ctx, "request_context") and ctx.request_context:
token = getattr(ctx.request_context, "access_token", None)
if token and hasattr(token, "claims"):
return token.claims
except Exception:
pass
return None
@ -192,154 +179,3 @@ def get_permission_summary() -> dict[str, list[str]]:
summary[level].sort()
return summary
class RBACMiddleware(Middleware):
"""FastMCP middleware for Role-Based Access Control.
Integrates with FastMCP's middleware system to enforce permissions
on every tool call based on OAuth group memberships.
Example:
mcp = FastMCP("my-server", auth=oauth_provider)
mcp.add_middleware(RBACMiddleware())
"""
def _extract_user_from_context(
self, fastmcp_ctx: "Context | None"
) -> dict[str, Any] | None:
"""Extract user claims from FastMCP context.
Uses FastMCP's dependency injection to retrieve the access token
from the current request's context variable.
Args:
fastmcp_ctx: FastMCP Context object (unused, kept for API compatibility).
Returns:
User claims dict from OAuth token, or None if not authenticated.
"""
try:
# FastMCP stores access token in a context variable, accessed via dependency
from fastmcp.server.dependencies import get_access_token
access_token = get_access_token()
if access_token and hasattr(access_token, "claims"):
return access_token.claims
except (RuntimeError, ImportError) as e:
# RuntimeError: No active HTTP request context
# ImportError: FastMCP auth dependencies not available
logger.debug("Could not get access token: %s", e)
return None
def _get_username(self, claims: dict[str, Any] | None) -> str:
"""Extract username from OAuth claims.
Args:
claims: OAuth token claims dict.
Returns:
Username string, or 'anonymous' if no claims.
"""
if not claims:
return "anonymous"
for claim in ("preferred_username", "email", "sub"):
if value := claims.get(claim):
return str(value)
return "unknown"
def _get_groups(self, claims: dict[str, Any] | None) -> list[str]:
"""Extract groups from OAuth claims.
Args:
claims: OAuth token claims dict.
Returns:
List of group names, or empty list if no claims.
"""
if not claims:
return []
groups = claims.get("groups", [])
if isinstance(groups, list):
return groups
return []
async def on_call_tool(
self,
context: MiddlewareContext[mt.CallToolRequestParams],
call_next: CallNext[mt.CallToolRequestParams, ToolResult],
) -> ToolResult:
"""Intercept tool calls to enforce RBAC permissions.
Args:
context: Middleware context containing tool call params.
call_next: Next handler in the middleware chain.
Returns:
Tool result if permitted.
Raises:
PermissionDeniedError: If user lacks required permission.
"""
# Extract tool name and arguments from the request
tool_name = context.message.name
tool_args = context.message.arguments or {}
# Get user info from OAuth context
claims = self._extract_user_from_context(context.fastmcp_context)
username = self._get_username(claims)
groups = self._get_groups(claims)
# Set up audit context for this request
set_current_user(claims)
# Check permission
if not check_permission(tool_name, groups):
required = get_required_permission(tool_name)
logger.warning(
"Permission denied: user=%s groups=%s tool=%s required=%s",
username,
groups,
tool_name,
required.value,
)
audit_permission_denied(tool_name, tool_args, required.value)
raise PermissionDeniedError(username, tool_name, required)
# Permission granted - execute tool with timing
start_time = time.perf_counter()
try:
result = await call_next(context)
duration_ms = (time.perf_counter() - start_time) * 1000
# Audit successful execution
# ToolResult can be complex, just log that it succeeded
audit_log(tool_name, tool_args, result="success", duration_ms=duration_ms)
logger.debug(
"Tool executed: user=%s tool=%s duration=%.2fms",
username,
tool_name,
duration_ms,
)
return result
except PermissionDeniedError:
# Re-raise without additional logging
raise
except Exception as e:
duration_ms = (time.perf_counter() - start_time) * 1000
audit_log(tool_name, tool_args, error=str(e), duration_ms=duration_ms)
logger.error(
"Tool failed: user=%s tool=%s error=%s duration=%.2fms",
username,
tool_name,
str(e),
duration_ms,
)
raise

31
src/mcvsphere/mixins/_base.py
View File

@ -1,31 +0,0 @@
"""Shared base for vSphere tool mixins — routes to the target ESXi host.
Tools that expose multi-host selection take a ``host`` argument and call
``self._conn(host)``. Tools that don't use ``self.conn``, which resolves to the
default (first) managed host. Both go through the ConnectionManager, so
connections are shared and established lazily.
"""
from typing import TYPE_CHECKING
from fastmcp.contrib.mcp_mixin import MCPMixin
if TYPE_CHECKING:
from mcvsphere.connection import VMwareConnection
from mcvsphere.connection_manager import ConnectionManager
class VSphereMixin(MCPMixin):
"""Base class giving every mixin host-aware connection access."""
def __init__(self, manager: "ConnectionManager"):
self.manager = manager
@property
def conn(self) -> "VMwareConnection":
"""The default host's connection (back-compat for single-host tools)."""
return self.manager.get()
def _conn(self, host: str | None = None) -> "VMwareConnection":
"""Resolve the connection for a specific managed host (default if None)."""
return self.manager.get(host)

39
src/mcvsphere/mixins/console.py
View File

@ -6,27 +6,27 @@ from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
import requests
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class ConsoleMixin(VSphereMixin):
class ConsoleMixin(MCPMixin):
"""VM console operations - screenshots and VMware Tools monitoring."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
@mcp_tool(
name="wait_for_vm_tools",
description="Wait for VMware Tools to become available on a VM. Useful after powering on a VM.",
annotations=ToolAnnotations(readOnlyHint=True),
)
def wait_for_vm_tools(
self, name: str, timeout: int = 120, poll_interval: int = 5,
host: str | None = None
self, name: str, timeout: int = 120, poll_interval: int = 5
) -> dict[str, Any]:
"""Wait for VMware Tools to become available.
@ -34,13 +34,11 @@ class ConsoleMixin(VSphereMixin):
name: VM name
timeout: Maximum seconds to wait (default: 120)
poll_interval: Seconds between status checks (default: 5)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with tools status, version, and guest info when ready
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -79,18 +77,16 @@ class ConsoleMixin(VSphereMixin):
description="Get current VMware Tools status for a VM",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_vm_tools_status(self, name: str, host: str | None = None) -> dict[str, Any]:
def get_vm_tools_status(self, name: str) -> dict[str, Any]:
"""Get VMware Tools status without waiting.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with current tools status and guest info
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -120,7 +116,6 @@ class ConsoleMixin(VSphereMixin):
name: str,
width: int | None = None,
height: int | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Capture VM console screenshot via vSphere HTTP API.
@ -128,21 +123,19 @@ class ConsoleMixin(VSphereMixin):
name: VM name
width: Optional width to scale the image
height: Optional height to scale the image
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with base64-encoded image data and metadata
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
# Build screenshot URL
# Format: https://{host}/screen?id={moid}
vcenter_host = conn.settings.vcenter_host
host = self.conn.settings.vcenter_host
moid = vm._moId
screenshot_url = f"https://{vcenter_host}/screen?id={moid}"
screenshot_url = f"https://{host}/screen?id={moid}"
# Add optional scaling parameters
params = []
@ -154,8 +147,8 @@ class ConsoleMixin(VSphereMixin):
screenshot_url += "&" + "&".join(params)
# Build auth header
username = conn.settings.vcenter_user
password = conn.settings.vcenter_password.get_secret_value()
username = self.conn.settings.vcenter_user
password = self.conn.settings.vcenter_password.get_secret_value()
auth = base64.b64encode(f"{username}:{password}".encode()).decode("ascii")
# Make request
@ -163,7 +156,7 @@ class ConsoleMixin(VSphereMixin):
response = requests.get(
screenshot_url,
headers={"Authorization": f"Basic {auth}"},
verify=not conn.settings.vcenter_insecure,
verify=not self.conn.settings.vcenter_insecure,
timeout=30,
)
response.raise_for_status()

241
src/mcvsphere/mixins/disk_management.py
View File

@ -2,19 +2,20 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class DiskManagementMixin(VSphereMixin):
class DiskManagementMixin(MCPMixin):
"""Virtual disk and ISO management tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _get_next_disk_unit_number(self, vm: vim.VirtualMachine) -> tuple[int, vim.vm.device.VirtualSCSIController]:
"""Find the next available SCSI unit number and controller."""
scsi_controllers = []
@ -64,104 +65,6 @@ class DiskManagementMixin(VSphereMixin):
return device
return None
def _find_free_ide_slot(
self, vm: vim.VirtualMachine
) -> tuple[int | None, int | None]:
"""Return (controllerKey, unitNumber) for a free IDE slot, or (None, None)."""
ide_controllers = [
d
for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualIDEController)
]
used: dict[int, set[int]] = {}
for d in vm.config.hardware.device:
if hasattr(d, "controllerKey") and hasattr(d, "unitNumber"):
used.setdefault(d.controllerKey, set()).add(d.unitNumber)
for controller in ide_controllers:
for unit in (0, 1): # each IDE controller holds two devices
if unit not in used.get(controller.key, set()):
return controller.key, unit
return None, None
@mcp_tool(
name="add_cdrom",
description="Add a CD/DVD drive to a VM, optionally mounting an ISO and booting from it",
annotations=ToolAnnotations(destructiveHint=True),
)
def add_cdrom(
self,
vm_name: str,
iso_path: str | None = None,
iso_datastore: str | None = None,
boot_from_iso: bool = False,
host: str | None = None,
) -> dict[str, Any]:
"""Add a CD/DVD drive to an existing VM.
Useful for appliances deployed from an OVA (e.g. Cisco CUCM), which
ship without a CD/DVD drive and must install from a bootable ISO.
Args:
vm_name: Name of the virtual machine
iso_path: ISO path on a datastore (e.g. 'iso/installer.iso') to mount
iso_datastore: Datastore holding the ISO (default: the VM's datastore)
boot_from_iso: Put the CD/DVD first in the boot order (for installers)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with the CD/DVD drive details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
controller_key, unit = self._find_free_ide_slot(vm)
if controller_key is None:
raise ValueError("No free IDE slot available for a CD/DVD drive")
cdrom_spec = vim.vm.device.VirtualDeviceSpec()
cdrom_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
cdrom_spec.device = vim.vm.device.VirtualCdrom()
cdrom_spec.device.controllerKey = controller_key
cdrom_spec.device.unitNumber = unit
cdrom_spec.device.key = -1
connectable = vim.vm.device.VirtualDevice.ConnectInfo()
connectable.allowGuestControl = True
connectable.connected = False
mounted_iso = None
if iso_path:
ds_name = iso_datastore or vm.config.files.vmPathName.split("]")[0].strip("[ ")
mounted_iso = f"[{ds_name}] {iso_path}"
backing = vim.vm.device.VirtualCdrom.IsoBackingInfo()
backing.fileName = mounted_iso
connectable.startConnected = True
else:
backing = vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo()
backing.deviceName = ""
backing.exclusive = False
connectable.startConnected = False
cdrom_spec.device.backing = backing
cdrom_spec.device.connectable = connectable
config_spec = vim.vm.ConfigSpec(deviceChange=[cdrom_spec])
if iso_path and boot_from_iso:
config_spec.bootOptions = vim.vm.BootOptions(
bootOrder=[vim.vm.BootOptions.BootableCdromDevice()]
)
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
return {
"vm": vm_name,
"action": "cdrom_added",
"iso": mounted_iso,
"boot_from_iso": bool(iso_path and boot_from_iso),
}
@mcp_tool(
name="add_disk",
description="Add a new virtual disk to a VM",
@ -173,7 +76,6 @@ class DiskManagementMixin(VSphereMixin):
size_gb: int,
thin_provisioned: bool = True,
datastore: str | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Add a new virtual disk to a VM.
@ -182,13 +84,11 @@ class DiskManagementMixin(VSphereMixin):
size_gb: Size of the new disk in GB
thin_provisioned: Use thin provisioning (default True)
datastore: Datastore for the disk (default: same as VM)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with new disk details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -197,7 +97,7 @@ class DiskManagementMixin(VSphereMixin):
# Determine datastore
if datastore:
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
ds_name = datastore
@ -212,7 +112,7 @@ class DiskManagementMixin(VSphereMixin):
backing = vim.vm.device.VirtualDisk.FlatVer2BackingInfo()
backing.diskMode = "persistent"
backing.thinProvisioned = thin_provisioned
backing.datastore = conn.find_datastore(ds_name)
backing.datastore = self.conn.find_datastore(ds_name)
# Create the virtual disk
disk = vim.vm.device.VirtualDisk()
@ -233,7 +133,7 @@ class DiskManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -255,7 +155,6 @@ class DiskManagementMixin(VSphereMixin):
vm_name: str,
disk_label: str,
delete_file: bool = False,
host: str | None = None,
) -> dict[str, Any]:
"""Remove a virtual disk from a VM.
@ -263,13 +162,11 @@ class DiskManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
disk_label: Label of disk to remove (e.g., 'Hard disk 2')
delete_file: Also delete the VMDK file (default False - keep file)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with removal details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -300,7 +197,7 @@ class DiskManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -321,7 +218,6 @@ class DiskManagementMixin(VSphereMixin):
vm_name: str,
disk_label: str,
new_size_gb: int,
host: str | None = None,
) -> dict[str, Any]:
"""Extend a virtual disk to a larger size.
@ -329,13 +225,11 @@ class DiskManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
disk_label: Label of disk to extend (e.g., 'Hard disk 1')
new_size_gb: New total size in GB (must be larger than current)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with extension details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -369,7 +263,7 @@ class DiskManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -384,18 +278,16 @@ class DiskManagementMixin(VSphereMixin):
description="List all virtual disks attached to a VM",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_disks(self, vm_name: str, host: str | None = None) -> list[dict[str, Any]]:
def list_disks(self, vm_name: str) -> list[dict[str, Any]]:
"""List all virtual disks attached to a VM.
Args:
vm_name: Name of the virtual machine
host: Managed ESXi host to target (default: the default host)
Returns:
List of disk details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -430,8 +322,6 @@ class DiskManagementMixin(VSphereMixin):
vm_name: str,
iso_path: str,
datastore: str | None = None,
cdrom_index: int = 0,
host: str | None = None,
) -> dict[str, Any]:
"""Attach an ISO file to a VM's CD/DVD drive.
@ -439,32 +329,17 @@ class DiskManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
iso_path: Path to ISO file on datastore (e.g., 'iso/ubuntu.iso')
datastore: Datastore containing the ISO (default: first VM datastore)
cdrom_index: Which CD/DVD drive to use, 0-based (default 0 = first).
Use 1 for a second drive, e.g. a Cisco answer-file ISO alongside
the bootable installer on drive 0.
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with attachment details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
cdroms = [
d
for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualCdrom)
]
if not cdroms:
cdrom = self._find_cdrom(vm)
if not cdrom:
raise ValueError(f"No CD/DVD drive found on VM '{vm_name}'")
if cdrom_index >= len(cdroms):
raise ValueError(
f"VM '{vm_name}' has {len(cdroms)} CD/DVD drive(s); "
f"cdrom_index={cdrom_index} is out of range"
)
cdrom = cdroms[cdrom_index]
# Determine datastore
if not datastore:
@ -495,7 +370,7 @@ class DiskManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -510,71 +385,55 @@ class DiskManagementMixin(VSphereMixin):
description="Detach/eject ISO from a VM's CD/DVD drive",
annotations=ToolAnnotations(destructiveHint=True),
)
def detach_iso(self, vm_name: str, host: str | None = None) -> dict[str, Any]:
def detach_iso(self, vm_name: str) -> dict[str, Any]:
"""Detach/eject ISO from a VM's CD/DVD drive.
Args:
vm_name: Name of the virtual machine
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with detachment details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
cdroms = [
d
for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualCdrom)
]
if not cdroms:
cdrom = self._find_cdrom(vm)
if not cdrom:
raise ValueError(f"No CD/DVD drive found on VM '{vm_name}'")
# Eject every drive that actually has an ISO mounted (a VM may have
# several CD/DVD drives; the ISO is rarely on the first one).
iso_cdroms = [
c
for c in cdroms
if isinstance(c.backing, vim.vm.device.VirtualCdrom.IsoBackingInfo)
]
if not iso_cdroms:
return {
"vm": vm_name,
"action": "no_iso_mounted",
"previous_iso": None,
"ejected": [],
}
# Get current ISO path for reporting
old_iso = None
if hasattr(cdrom.backing, "fileName"):
old_iso = cdrom.backing.fileName
device_changes = []
ejected = []
for cdrom in iso_cdroms:
ejected.append(
{"cdrom": cdrom.deviceInfo.label, "previous_iso": cdrom.backing.fileName}
)
backing = vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo()
backing.deviceName = ""
backing.exclusive = False
cdrom.backing = backing
cdrom.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
cdrom.connectable.connected = False
cdrom.connectable.startConnected = False
cdrom.connectable.allowGuestControl = True
# Create empty client device backing (ejects the ISO)
backing = vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo()
backing.deviceName = ""
spec = vim.vm.device.VirtualDeviceSpec()
spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
spec.device = cdrom
device_changes.append(spec)
# Configure CD-ROM
cdrom.backing = backing
cdrom.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
cdrom.connectable.connected = False
cdrom.connectable.startConnected = False
cdrom.connectable.allowGuestControl = True
config_spec = vim.vm.ConfigSpec(deviceChange=device_changes)
# Create device edit spec
cdrom_spec = vim.vm.device.VirtualDeviceSpec()
cdrom_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
cdrom_spec.device = cdrom
# Create VM config spec
config_spec = vim.vm.ConfigSpec()
config_spec.deviceChange = [cdrom_spec]
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
"action": "iso_detached",
"previous_iso": ejected[0]["previous_iso"],
"ejected": ejected,
"previous_iso": old_iso,
"cdrom": cdrom.deviceInfo.label,
}

63
src/mcvsphere/mixins/guest_ops.py
View File

@ -4,19 +4,20 @@ import base64
import time
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class GuestOpsMixin(VSphereMixin):
class GuestOpsMixin(MCPMixin):
"""Guest OS operations (requires VMware Tools running in the VM)."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _get_guest_auth(
self, username: str, password: str
) -> vim.vm.guest.NamePasswordAuthentication:
@ -53,7 +54,6 @@ class GuestOpsMixin(VSphereMixin):
working_directory: str = "",
wait_for_completion: bool = True,
timeout_seconds: int = 300,
host: str | None = None,
) -> dict[str, Any]:
"""Run a command in the guest OS.
@ -66,16 +66,14 @@ class GuestOpsMixin(VSphereMixin):
working_directory: Working directory for the command
wait_for_completion: Wait for command to complete
timeout_seconds: Timeout in seconds (only if waiting)
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
process_manager = guest_ops.processManager
auth = self._get_guest_auth(username, password)
@ -121,17 +119,16 @@ class GuestOpsMixin(VSphereMixin):
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_guest_processes(
self, name: str, username: str, password: str, host: str | None = None
self, name: str, username: str, password: str
) -> list[dict[str, Any]]:
"""List processes running in the guest OS."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
process_manager = guest_ops.processManager
auth = self._get_guest_auth(username, password)
@ -154,8 +151,7 @@ class GuestOpsMixin(VSphereMixin):
annotations=ToolAnnotations(readOnlyHint=True),
)
def read_guest_file(
self, name: str, username: str, password: str, guest_path: str,
host: str | None = None
self, name: str, username: str, password: str, guest_path: str
) -> dict[str, Any]:
"""Read a file from the guest OS.
@ -164,16 +160,14 @@ class GuestOpsMixin(VSphereMixin):
username: Guest OS username
password: Guest OS password
guest_path: Path to file in guest (e.g., /etc/hosts, C:\\Windows\\System32\\hosts)
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
file_manager = guest_ops.fileManager
auth = self._get_guest_auth(username, password)
@ -234,7 +228,6 @@ class GuestOpsMixin(VSphereMixin):
guest_path: str,
content: str,
overwrite: bool = True,
host: str | None = None,
) -> str:
"""Write a file to the guest OS.
@ -245,16 +238,14 @@ class GuestOpsMixin(VSphereMixin):
guest_path: Destination path in guest
content: File content (text)
overwrite: Overwrite if exists
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
file_manager = guest_ops.fileManager
auth = self._get_guest_auth(username, password)
@ -297,18 +288,16 @@ class GuestOpsMixin(VSphereMixin):
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_guest_directory(
self, name: str, username: str, password: str, guest_path: str,
host: str | None = None
self, name: str, username: str, password: str, guest_path: str
) -> list[dict[str, Any]]:
"""List files in a guest directory."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
file_manager = guest_ops.fileManager
auth = self._get_guest_auth(username, password)
@ -343,17 +332,15 @@ class GuestOpsMixin(VSphereMixin):
password: str,
guest_path: str,
create_parents: bool = True,
host: str | None = None,
) -> str:
"""Create a directory in the guest OS."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
file_manager = guest_ops.fileManager
auth = self._get_guest_auth(username, password)
@ -369,18 +356,16 @@ class GuestOpsMixin(VSphereMixin):
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def delete_guest_file(
self, name: str, username: str, password: str, guest_path: str,
host: str | None = None
self, name: str, username: str, password: str, guest_path: str
) -> str:
"""Delete a file or directory from the guest OS."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
self._check_tools_running(vm)
guest_ops = conn.content.guestOperationsManager
guest_ops = self.conn.content.guestOperationsManager
file_manager = guest_ops.fileManager
auth = self._get_guest_auth(username, password)

103
src/mcvsphere/mixins/host_management.py
View File

@ -2,22 +2,23 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class HostManagementMixin(VSphereMixin):
class HostManagementMixin(MCPMixin):
"""ESXi host management tools."""
def _get_host(self, conn) -> vim.HostSystem:
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _get_host(self) -> vim.HostSystem:
"""Get the ESXi host system."""
for entity in conn.datacenter.hostFolder.childEntity:
for entity in self.conn.datacenter.hostFolder.childEntity:
if isinstance(entity, vim.ComputeResource):
if entity.host:
return entity.host[0]
@ -30,17 +31,13 @@ class HostManagementMixin(VSphereMixin):
description="Get detailed information about the ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_host_info(self, host: str | None = None) -> dict[str, Any]:
def get_host_info(self) -> dict[str, Any]:
"""Get detailed ESXi host information.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with host details including hardware, software, and status
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
summary = host.summary
hardware = summary.hardware
config = summary.config
@ -84,20 +81,17 @@ class HostManagementMixin(VSphereMixin):
self,
evacuate_vms: bool = True,
timeout_seconds: int = 300,
host: str | None = None,
) -> dict[str, Any]:
"""Put ESXi host into maintenance mode.
Args:
evacuate_vms: Evacuate/suspend VMs before entering (default True)
timeout_seconds: Timeout for the operation (default 300)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
if host.runtime.inMaintenanceMode:
return {
@ -111,7 +105,7 @@ class HostManagementMixin(VSphereMixin):
timeout=timeout_seconds,
evacuatePoweredOffVms=evacuate_vms,
)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"host": host.name,
@ -128,19 +122,16 @@ class HostManagementMixin(VSphereMixin):
def exit_maintenance_mode(
self,
timeout_seconds: int = 300,
host: str | None = None,
) -> dict[str, Any]:
"""Exit ESXi host from maintenance mode.
Args:
timeout_seconds: Timeout for the operation (default 300)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
if not host.runtime.inMaintenanceMode:
return {
@ -150,7 +141,7 @@ class HostManagementMixin(VSphereMixin):
}
task = host.ExitMaintenanceMode_Task(timeout=timeout_seconds)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"host": host.name,
@ -163,17 +154,13 @@ class HostManagementMixin(VSphereMixin):
description="List all services on the ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_services(self, host: str | None = None) -> list[dict[str, Any]]:
def list_services(self) -> list[dict[str, Any]]:
"""List all services on the ESXi host.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
List of service details
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
service_system = host.configManager.serviceSystem
services = []
@ -194,18 +181,16 @@ class HostManagementMixin(VSphereMixin):
description="Start a service on the ESXi host",
annotations=ToolAnnotations(destructiveHint=True),
)
def start_service(self, service_key: str, host: str | None = None) -> dict[str, Any]:
def start_service(self, service_key: str) -> dict[str, Any]:
"""Start a service on the ESXi host.
Args:
service_key: Service key (e.g., 'TSM-SSH', 'ntpd', 'sfcbd')
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
service_system = host.configManager.serviceSystem
# Verify service exists
@ -241,18 +226,16 @@ class HostManagementMixin(VSphereMixin):
description="Stop a service on the ESXi host",
annotations=ToolAnnotations(destructiveHint=True),
)
def stop_service(self, service_key: str, host: str | None = None) -> dict[str, Any]:
def stop_service(self, service_key: str) -> dict[str, Any]:
"""Stop a service on the ESXi host.
Args:
service_key: Service key (e.g., 'TSM-SSH', 'ntpd')
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
service_system = host.configManager.serviceSystem
# Verify service exists
@ -292,20 +275,17 @@ class HostManagementMixin(VSphereMixin):
self,
service_key: str,
policy: str,
host: str | None = None,
) -> dict[str, Any]:
"""Set the startup policy for a service.
Args:
service_key: Service key (e.g., 'TSM-SSH', 'ntpd')
policy: Startup policy - 'on' (auto), 'off' (manual), 'automatic'
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
service_system = host.configManager.serviceSystem
valid_policies = ["on", "off", "automatic"]
@ -339,17 +319,13 @@ class HostManagementMixin(VSphereMixin):
description="Get NTP configuration for the ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_ntp_config(self, host: str | None = None) -> dict[str, Any]:
def get_ntp_config(self) -> dict[str, Any]:
"""Get NTP configuration for the ESXi host.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with NTP configuration
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
datetime_system = host.configManager.dateTimeSystem
ntp_config = datetime_system.dateTimeInfo.ntpConfig
@ -382,20 +358,17 @@ class HostManagementMixin(VSphereMixin):
self,
ntp_servers: list[str],
start_service: bool = True,
host: str | None = None,
) -> dict[str, Any]:
"""Configure NTP servers for the ESXi host.
Args:
ntp_servers: List of NTP server addresses
start_service: Start ntpd service after configuring (default True)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with configuration result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
datetime_system = host.configManager.dateTimeSystem
# Create NTP config
@ -434,18 +407,16 @@ class HostManagementMixin(VSphereMixin):
description="Reboot the ESXi host (requires maintenance mode)",
annotations=ToolAnnotations(destructiveHint=True),
)
def reboot_host(self, force: bool = False, host: str | None = None) -> dict[str, Any]:
def reboot_host(self, force: bool = False) -> dict[str, Any]:
"""Reboot the ESXi host.
Args:
force: Force reboot even if VMs are running (dangerous!)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
if not host.runtime.inMaintenanceMode and not force:
raise ValueError(
@ -468,18 +439,16 @@ class HostManagementMixin(VSphereMixin):
description="Shutdown the ESXi host (requires maintenance mode)",
annotations=ToolAnnotations(destructiveHint=True),
)
def shutdown_host(self, force: bool = False, host: str | None = None) -> dict[str, Any]:
def shutdown_host(self, force: bool = False) -> dict[str, Any]:
"""Shutdown the ESXi host.
Args:
force: Force shutdown even if VMs are running (dangerous!)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with operation result
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
if not host.runtime.inMaintenanceMode and not force:
raise ValueError(
@ -502,17 +471,13 @@ class HostManagementMixin(VSphereMixin):
description="Get detailed hardware information for the ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_host_hardware(self, host: str | None = None) -> dict[str, Any]:
def get_host_hardware(self) -> dict[str, Any]:
"""Get detailed hardware information.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with hardware details
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
hardware = host.hardware
# CPU info
@ -568,17 +533,13 @@ class HostManagementMixin(VSphereMixin):
description="Get network configuration for the ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_host_networking(self, host: str | None = None) -> dict[str, Any]:
def get_host_networking(self) -> dict[str, Any]:
"""Get network configuration for the ESXi host.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with networking details
"""
conn = self._conn(host)
host = self._get_host(conn)
host = self._get_host()
network_config = host.config.network
# Virtual switches

88
src/mcvsphere/mixins/monitoring.py
View File

@ -3,32 +3,28 @@
from datetime import UTC, datetime, timedelta
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class MonitoringMixin(VSphereMixin):
class MonitoringMixin(MCPMixin):
"""VM and host monitoring tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
@mcp_tool(
name="get_vm_stats",
description="Get current performance statistics for a virtual machine",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_vm_stats(self, name: str, host: str | None = None) -> dict[str, Any]:
"""Get VM performance statistics.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def get_vm_stats(self, name: str) -> dict[str, Any]:
"""Get VM performance statistics."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -63,25 +59,19 @@ class MonitoringMixin(VSphereMixin):
description="Get performance statistics for an ESXi host",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_host_stats(
self, host_name: str | None = None, host: str | None = None
) -> dict[str, Any]:
def get_host_stats(self, host_name: str | None = None) -> dict[str, Any]:
"""Get ESXi host performance statistics.
If host_name is not provided, returns stats for the first host.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
if host_name:
host = conn.find_host(host_name)
host = self.conn.find_host(host_name)
if not host:
raise ValueError(f"Host '{host_name}' not found")
else:
# Get first host
container = conn.content.viewManager.CreateContainerView(
conn.content.rootFolder, [vim.HostSystem], True
container = self.conn.content.viewManager.CreateContainerView(
self.conn.content.rootFolder, [vim.HostSystem], True
)
try:
hosts = list(container.view)
@ -128,15 +118,10 @@ class MonitoringMixin(VSphereMixin):
description="List all ESXi hosts in the datacenter",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_hosts(self, host: str | None = None) -> list[dict[str, Any]]:
"""List all ESXi hosts with basic info.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
container = conn.content.viewManager.CreateContainerView(
conn.content.rootFolder, [vim.HostSystem], True
def list_hosts(self) -> list[dict[str, Any]]:
"""List all ESXi hosts with basic info."""
container = self.conn.content.viewManager.CreateContainerView(
self.conn.content.rootFolder, [vim.HostSystem], True
)
try:
hosts = []
@ -163,16 +148,9 @@ class MonitoringMixin(VSphereMixin):
description="Get recent vSphere tasks (VM operations, etc.)",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_recent_tasks(
self, count: int = 20, host: str | None = None
) -> list[dict[str, Any]]:
"""Get recent vSphere tasks.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
task_manager = conn.content.taskManager
def get_recent_tasks(self, count: int = 20) -> list[dict[str, Any]]:
"""Get recent vSphere tasks."""
task_manager = self.conn.content.taskManager
recent_tasks = task_manager.recentTask[:count] if task_manager.recentTask else []
tasks = []
@ -210,15 +188,10 @@ class MonitoringMixin(VSphereMixin):
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_recent_events(
self, count: int = 50, hours: int = 24, host: str | None = None
self, count: int = 50, hours: int = 24
) -> list[dict[str, Any]]:
"""Get recent vSphere events.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
event_manager = conn.content.eventManager
"""Get recent vSphere events."""
event_manager = self.conn.content.eventManager
# Create time filter
time_filter = vim.event.EventFilterSpec.ByTime()
@ -262,22 +235,17 @@ class MonitoringMixin(VSphereMixin):
description="Get triggered alarms in the datacenter",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_alarms(self, host: str | None = None) -> list[dict[str, Any]]:
"""Get all triggered alarms.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
def get_alarms(self) -> list[dict[str, Any]]:
"""Get all triggered alarms."""
alarms = []
# Check datacenter alarms
if conn.datacenter.triggeredAlarmState:
for alarm_state in conn.datacenter.triggeredAlarmState:
if self.conn.datacenter.triggeredAlarmState:
for alarm_state in self.conn.datacenter.triggeredAlarmState:
alarms.append(self._format_alarm(alarm_state))
# Check VM alarms
for vm in conn.get_all_vms():
for vm in self.conn.get_all_vms():
if vm.triggeredAlarmState:
for alarm_state in vm.triggeredAlarmState:
alarms.append(self._format_alarm(alarm_state, vm.name))

62
src/mcvsphere/mixins/nic_management.py
View File

@ -2,19 +2,20 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class NICManagementMixin(VSphereMixin):
class NICManagementMixin(MCPMixin):
"""Virtual network adapter management tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _find_nic_by_label(
self, vm: vim.VirtualMachine, label: str
) -> vim.vm.device.VirtualEthernetCard | None:
@ -28,10 +29,10 @@ class NICManagementMixin(VSphereMixin):
return None
def _get_network_backing(
self, conn, network_name: str
self, network_name: str
) -> vim.vm.device.VirtualEthernetCard.NetworkBackingInfo:
"""Get the appropriate backing info for a network."""
network = conn.find_network(network_name)
network = self.conn.find_network(network_name)
if not network:
raise ValueError(f"Network '{network_name}' not found")
@ -54,18 +55,16 @@ class NICManagementMixin(VSphereMixin):
description="List all network adapters attached to a VM",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_nics(self, vm_name: str, host: str | None = None) -> list[dict[str, Any]]:
def list_nics(self, vm_name: str) -> list[dict[str, Any]]:
"""List all virtual network adapters on a VM.
Args:
vm_name: Name of the virtual machine
host: Managed ESXi host to target (default: the default host)
Returns:
List of NIC details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -89,7 +88,7 @@ class NICManagementMixin(VSphereMixin):
# For distributed switch, look up the portgroup name
nic_info["network"] = f"DVS:{backing.port.portgroupKey}"
# Try to get actual name
for net in conn.datacenter.networkFolder.childEntity:
for net in self.conn.datacenter.networkFolder.childEntity:
if hasattr(net, "key") and net.key == backing.port.portgroupKey:
nic_info["network"] = net.name
break
@ -109,7 +108,6 @@ class NICManagementMixin(VSphereMixin):
network: str,
nic_type: str = "vmxnet3",
start_connected: bool = True,
host: str | None = None,
) -> dict[str, Any]:
"""Add a new network adapter to a VM.
@ -118,13 +116,11 @@ class NICManagementMixin(VSphereMixin):
network: Network/portgroup name to connect to
nic_type: Adapter type - vmxnet3 (default), e1000, e1000e
start_connected: Connect adapter when VM powers on (default True)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with new NIC details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -142,7 +138,7 @@ class NICManagementMixin(VSphereMixin):
# Create the NIC
nic = nic_class()
nic.backing = self._get_network_backing(conn, network)
nic.backing = self._get_network_backing(network)
nic.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
nic.connectable.startConnected = start_connected
nic.connectable.connected = False # Can't connect until powered on
@ -160,7 +156,7 @@ class NICManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
# Get the MAC address that was assigned
vm.Reload()
@ -195,20 +191,17 @@ class NICManagementMixin(VSphereMixin):
self,
vm_name: str,
nic_label: str,
host: str | None = None,
) -> dict[str, Any]:
"""Remove a network adapter from a VM.
Args:
vm_name: Name of the virtual machine
nic_label: Label of NIC to remove (e.g., 'Network adapter 1')
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with removal details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -238,7 +231,7 @@ class NICManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -258,7 +251,6 @@ class NICManagementMixin(VSphereMixin):
vm_name: str,
nic_label: str,
new_network: str,
host: str | None = None,
) -> dict[str, Any]:
"""Change which network a NIC is connected to.
@ -266,13 +258,11 @@ class NICManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
nic_label: Label of NIC to modify (e.g., 'Network adapter 1')
new_network: New network/portgroup name
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with change details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -291,7 +281,7 @@ class NICManagementMixin(VSphereMixin):
old_network = nic.backing.deviceName
# Update backing to new network
nic.backing = self._get_network_backing(conn, new_network)
nic.backing = self._get_network_backing(new_network)
# Create device edit spec
nic_spec = vim.vm.device.VirtualDeviceSpec()
@ -304,7 +294,7 @@ class NICManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -325,7 +315,6 @@ class NICManagementMixin(VSphereMixin):
vm_name: str,
nic_label: str,
connected: bool = True,
host: str | None = None,
) -> dict[str, Any]:
"""Connect or disconnect a NIC on a running VM.
@ -333,13 +322,11 @@ class NICManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
nic_label: Label of NIC (e.g., 'Network adapter 1')
connected: True to connect, False to disconnect
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with connection status
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -369,7 +356,7 @@ class NICManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -388,7 +375,6 @@ class NICManagementMixin(VSphereMixin):
vm_name: str,
nic_label: str,
mac_address: str,
host: str | None = None,
) -> dict[str, Any]:
"""Set a custom MAC address for a NIC.
@ -396,13 +382,11 @@ class NICManagementMixin(VSphereMixin):
vm_name: Name of the virtual machine
nic_label: Label of NIC (e.g., 'Network adapter 1')
mac_address: MAC address in format XX:XX:XX:XX:XX:XX
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with MAC address change details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -437,7 +421,7 @@ class NICManagementMixin(VSphereMixin):
# Reconfigure VM
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,

542
src/mcvsphere/mixins/ovf_management.py
View File

@ -1,32 +1,26 @@
"""OVF/OVA Management - deploy and export virtual appliances."""
import contextlib
import http.client
import shutil
import ssl
import tarfile
import tempfile
import threading
import time
import urllib.request
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import TYPE_CHECKING, Any
from urllib.parse import urlparse
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class OVFManagementMixin(VSphereMixin):
class OVFManagementMixin(MCPMixin):
"""OVF/OVA deployment and export tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _extract_ova(self, ova_path: str) -> tuple[str, str, list[str]]:
"""Extract OVA file and return (temp_dir, ovf_path, disk_files)."""
temp_dir = tempfile.mkdtemp(prefix="ovf_")
@ -56,12 +50,11 @@ class OVFManagementMixin(VSphereMixin):
_lease: vim.HttpNfcLease,
disk_path: str,
device_url: str,
conn,
) -> None:
"""Upload a disk file via NFC lease."""
# Create SSL context
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
if self.conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
@ -75,8 +68,8 @@ class OVFManagementMixin(VSphereMixin):
request.add_header("Connection", "Keep-Alive")
# Add session cookie
if hasattr(conn.service_instance, "_stub"):
cookie = conn.service_instance._stub.cookie
if hasattr(self.conn.service_instance, "_stub"):
cookie = self.conn.service_instance._stub.cookie
if cookie:
request.add_header("Cookie", cookie)
@ -97,7 +90,6 @@ class OVFManagementMixin(VSphereMixin):
datastore: str,
network: str | None = None,
power_on: bool = False,
host: str | None = None,
) -> dict[str, Any]:
"""Deploy a virtual machine from an OVF or OVA file.
@ -109,23 +101,21 @@ class OVFManagementMixin(VSphereMixin):
datastore: Target datastore for VM files
network: Network to connect VM to (optional)
power_on: Power on VM after deployment (default False)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with deployment details
"""
conn = self._conn(host)
# Get OVF Manager
ovf_manager = conn.content.ovfManager
ovf_manager = self.conn.content.ovfManager
# Find target datastore
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
# Get resource pool and folder
host = None
for h in conn.datacenter.hostFolder.childEntity:
for h in self.conn.datacenter.hostFolder.childEntity:
if hasattr(h, "host"):
host = h.host[0] if h.host else None
break
@ -143,7 +133,7 @@ class OVFManagementMixin(VSphereMixin):
resource_pool = host.parent.resourcePool
# Get VM folder
vm_folder = conn.datacenter.vmFolder
vm_folder = self.conn.datacenter.vmFolder
# Read OVF descriptor from datastore
# For OVA, we need to extract first
@ -158,7 +148,7 @@ class OVFManagementMixin(VSphereMixin):
)
# Read OVF descriptor via datastore browser
ovf_descriptor = self._read_datastore_file(datastore, ovf_path, conn)
ovf_descriptor = self._read_datastore_file(datastore, ovf_path)
# Create import spec params
import_spec_params = vim.OvfManager.CreateImportSpecParams(
@ -168,7 +158,7 @@ class OVFManagementMixin(VSphereMixin):
# If network specified, add network mapping
if network:
net = conn.find_network(network)
net = self.conn.find_network(network)
if net:
network_mapping = vim.OvfManager.NetworkMapping(
name="VM Network", # Common default in OVF
@ -217,7 +207,7 @@ class OVFManagementMixin(VSphereMixin):
lease.Complete()
# Find the newly created VM
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
result = {
"vm": vm_name,
@ -230,35 +220,35 @@ class OVFManagementMixin(VSphereMixin):
result["uuid"] = vm.config.uuid
if power_on:
task = vm.PowerOnVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
result["power_state"] = "poweredOn"
else:
result["power_state"] = "poweredOff"
return result
def _read_datastore_file(self, datastore: str, path: str, conn) -> str:
def _read_datastore_file(self, datastore: str, path: str) -> str:
"""Read a text file from datastore."""
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
# Build HTTP URL
dc_name = conn.datacenter.name
dc_name = self.conn.datacenter.name
url = (
f"https://{conn.settings.vcenter_host}/folder/{path}"
f"https://{self.conn.settings.vcenter_host}/folder/{path}"
f"?dcPath={dc_name}&dsName={datastore}"
)
# Setup request
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
if self.conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
request = urllib.request.Request(url)
if hasattr(conn.service_instance, "_stub"):
cookie = conn.service_instance._stub.cookie
if hasattr(self.conn.service_instance, "_stub"):
cookie = self.conn.service_instance._stub.cookie
if cookie:
request.add_header("Cookie", cookie)
@ -273,452 +263,6 @@ class OVFManagementMixin(VSphereMixin):
# For now, document this limitation
pass
def _resolve_ova_file(self, ova_path: str, conn) -> tuple[str, bool]:
"""Return (local_path, is_temp); downloads the OVA first if a URL is given."""
if ova_path.startswith(("http://", "https://")):
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
fd, tmp = tempfile.mkstemp(suffix=".ova", prefix="ova_dl_")
with open(fd, "wb") as out:
req = urllib.request.Request(ova_path)
with urllib.request.urlopen(req, context=context) as resp:
shutil.copyfileobj(resp, out)
return tmp, True
if not Path(ova_path).is_file():
raise ValueError(f"OVA file not found: {ova_path}")
return ova_path, False
@staticmethod
def _parse_ovf_network_names(ovf_xml: str) -> list[str]:
"""Extract declared network names from an OVF descriptor's NetworkSection."""
names: list[str] = []
try:
root = ET.fromstring(ovf_xml)
except ET.ParseError:
return names
for el in root.iter():
if el.tag.rsplit("}", 1)[-1] == "Network":
for key, val in el.attrib.items():
if key.rsplit("}", 1)[-1] == "name":
names.append(val)
return names
def _put_stream_to_lease(
self, device_url: str, fileobj: Any, size: int, conn
) -> None:
"""Stream a file object to an NFC lease device URL via chunked HTTP PUT."""
parsed = urlparse(device_url)
host = parsed.hostname
# ESXi returns '*' (meaning "the host you connected to") or its own
# mgmt name. For a direct host connection the only address we know is
# reachable is the one we connected on, so use that.
if (
not host
or host == "*"
or conn.content.about.apiType == "HostAgent"
):
host = conn.settings.vcenter_host
port = parsed.port or 443
path = parsed.path + (f"?{parsed.query}" if parsed.query else "")
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
http_conn = http.client.HTTPSConnection(
host, port, context=context, timeout=900
)
try:
http_conn.putrequest(
"PUT", path, skip_host=True, skip_accept_encoding=True
)
http_conn.putheader("Host", host)
http_conn.putheader("Content-Length", str(size))
http_conn.putheader("Content-Type", "application/x-vnd.vmware-streamVmdk")
# ImportVApp pre-creates the disk file, so the NFC stream must
# explicitly overwrite it (else ESXi returns 403 "File exists").
http_conn.putheader("Overwrite", "t")
cookie = getattr(conn.si._stub, "cookie", None)
if cookie:
http_conn.putheader("Cookie", cookie)
http_conn.endheaders()
while True:
chunk = fileobj.read(1024 * 1024)
if not chunk:
break
http_conn.send(chunk)
resp = http_conn.getresponse()
resp.read()
if resp.status not in (200, 201):
raise ValueError(
f"Disk upload failed: HTTP {resp.status} {resp.reason}"
)
finally:
http_conn.close()
@mcp_tool(
name="deploy_ova",
description="Deploy a VM from an OVA file (local path or URL) by streaming it to the host over an NFC lease",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False),
)
def deploy_ova(
self,
ova_path: str,
vm_name: str,
datastore: str | None = None,
network: str | None = None,
power_on: bool = False,
disk_provisioning: str = "thin",
deployment_option: str | None = None,
iso_path: str | None = None,
iso_datastore: str | None = None,
boot_from_iso: bool = True,
host: str | None = None,
) -> dict[str, Any]:
"""Deploy a virtual machine from an OVA file.
The OVA is read from the MCP server host (local filesystem path) or
downloaded if an http(s) URL is given, then streamed to the ESXi host
over an NFC lease. Unlike datastore-based deploy, the OVA does not need
to be pre-staged on a datastore.
Args:
ova_path: Local path to the .ova file, or an http(s) URL to download
vm_name: Name for the new VM
datastore: Target datastore (default: largest available)
network: Target port group; every network in the OVF is mapped to it
power_on: Power on the VM after deployment
disk_provisioning: 'thin', 'thick', or 'eagerZeroedThick'
deployment_option: OVF configuration id for multi-config templates
(e.g. Cisco 'S'/'M'/'L'); defaults to the OVF's default config.
Use inspect_ova to list available options.
iso_path: ISO on a datastore to mount in a new CD/DVD drive after
deploy (for diskless appliance OVAs like CUCM that install from
a bootable ISO). A CD/DVD drive is added automatically.
iso_datastore: Datastore holding the ISO (default: the VM's datastore)
boot_from_iso: When an ISO is given, put the CD/DVD first in boot order
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with deployment details
"""
conn = self._conn(host)
ds = conn.find_datastore(datastore) if datastore else conn.datastore
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
resource_pool = conn.resource_pool
vm_folder = conn.datacenter.vmFolder
# An ESXi host is required as the import target
view = conn.content.viewManager.CreateContainerView(
conn.content.rootFolder, [vim.HostSystem], True
)
hosts = list(view.view)
view.Destroy()
host_system = hosts[0] if hosts else None
local_ova, is_temp = self._resolve_ova_file(ova_path, conn)
import_spec = None
try:
with tarfile.open(local_ova) as tar:
ovf_member = next(
(m for m in tar.getmembers() if m.name.lower().endswith(".ovf")),
None,
)
if not ovf_member:
raise ValueError("No .ovf descriptor found in OVA")
ovf_xml = tar.extractfile(ovf_member).read().decode("utf-8")
# Build the import spec, mapping every OVF network to the target
spec_params = vim.OvfManager.CreateImportSpecParams(
entityName=vm_name,
diskProvisioning=disk_provisioning,
)
if deployment_option:
spec_params.deploymentOption = deployment_option
if network:
net = conn.find_network(network)
if not net:
raise ValueError(f"Network '{network}' not found")
ovf_nets = self._parse_ovf_network_names(ovf_xml) or ["VM Network"]
spec_params.networkMapping = [
vim.OvfManager.NetworkMapping(name=n, network=net)
for n in ovf_nets
]
ovf_manager = conn.content.ovfManager
import_spec = ovf_manager.CreateImportSpec(
ovfDescriptor=ovf_xml,
resourcePool=resource_pool,
datastore=ds,
cisp=spec_params,
)
if import_spec.error:
raise ValueError(
"OVF import errors: "
+ "; ".join(str(e.msg) for e in import_spec.error)
)
lease = resource_pool.ImportVApp(
spec=import_spec.importSpec, folder=vm_folder, host=host_system
)
while lease.state == vim.HttpNfcLease.State.initializing:
time.sleep(0.1)
if lease.state == vim.HttpNfcLease.State.error:
raise ValueError(f"NFC lease error: {lease.error}")
# Stream each disk to its lease URL, keeping the lease alive
total = sum(max(fi.size, 1) for fi in import_spec.fileItem) or 1
uploaded = [0]
stop = threading.Event()
def _keepalive() -> None:
while not stop.wait(20):
try:
lease.HttpNfcLeaseProgress(
min(99, int(uploaded[0] * 100 / total))
)
except Exception:
return
keeper = threading.Thread(target=_keepalive, daemon=True)
keeper.start()
try:
url_by_key = {du.importKey: du.url for du in lease.info.deviceUrl}
with tarfile.open(local_ova) as tar:
by_base = {m.name.rsplit("/", 1)[-1]: m for m in tar.getmembers()}
for fi in import_spec.fileItem:
device_url = url_by_key.get(fi.deviceId)
if not device_url:
raise ValueError(f"No lease URL for device {fi.deviceId}")
member = by_base.get(fi.path.rsplit("/", 1)[-1])
if not member:
raise ValueError(f"Disk '{fi.path}' missing from OVA")
src = tar.extractfile(member)
self._put_stream_to_lease(
device_url, src, member.size, conn
)
uploaded[0] += member.size
lease.HttpNfcLeaseProgress(
min(99, int(uploaded[0] * 100 / total))
)
lease.HttpNfcLeaseProgress(100)
lease.Complete()
except Exception:
with contextlib.suppress(Exception):
lease.Abort()
raise
finally:
stop.set()
finally:
if is_temp:
Path(local_ova).unlink(missing_ok=True)
vm = conn.find_vm(vm_name)
result: dict[str, Any] = {
"vm": vm_name,
"action": "ova_deployed",
"datastore": ds.name,
"source": ova_path,
"disks": len(import_spec.fileItem) if import_spec else 0,
}
if vm:
result["uuid"] = vm.config.uuid
if iso_path:
result["iso"] = self._add_cdrom_with_iso(
vm, iso_path, iso_datastore, boot_from_iso, conn
)
if power_on:
task = vm.PowerOnVM_Task()
conn.wait_for_task(task)
result["power_state"] = "poweredOn"
else:
result["power_state"] = "poweredOff"
return result
def _add_cdrom_with_iso(
self,
vm: vim.VirtualMachine,
iso_path: str,
iso_datastore: str | None,
boot_from_iso: bool,
conn,
) -> str:
"""Mount an ISO in the VM's CD/DVD drive (reusing the first existing
drive, or adding one if none exist) and optionally boot from it.
Reusing the existing primary drive matters: many appliance OVAs (e.g.
Cisco CUCM) already define empty CD/DVD drives, and the BIOS boots the
first one, so the ISO must land there rather than on a newly-added
secondary drive.
Returns the mounted datastore ISO path.
"""
ds_name = iso_datastore or vm.config.files.vmPathName.split("]")[0].strip("[ ")
mounted = f"[{ds_name}] {iso_path}"
backing = vim.vm.device.VirtualCdrom.IsoBackingInfo()
backing.fileName = mounted
connectable = vim.vm.device.VirtualDevice.ConnectInfo()
connectable.allowGuestControl = True
connectable.startConnected = True
connectable.connected = (
vm.runtime.powerState == vim.VirtualMachinePowerState.poweredOn
)
existing = next(
(
d
for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualCdrom)
),
None,
)
cdrom_spec = vim.vm.device.VirtualDeviceSpec()
if existing is not None:
existing.backing = backing
existing.connectable = connectable
cdrom_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
cdrom_spec.device = existing
else:
# No drive present — add one on a free IDE slot
used: dict[int, set[int]] = {}
ide_controllers = []
for d in vm.config.hardware.device:
if isinstance(d, vim.vm.device.VirtualIDEController):
ide_controllers.append(d)
if hasattr(d, "controllerKey") and hasattr(d, "unitNumber"):
used.setdefault(d.controllerKey, set()).add(d.unitNumber)
controller_key = unit = None
for controller in ide_controllers:
for candidate in (0, 1):
if candidate not in used.get(controller.key, set()):
controller_key, unit = controller.key, candidate
break
if controller_key is not None:
break
if controller_key is None:
raise ValueError("No free IDE slot for a CD/DVD drive")
cdrom_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
cdrom_spec.device = vim.vm.device.VirtualCdrom()
cdrom_spec.device.controllerKey = controller_key
cdrom_spec.device.unitNumber = unit
cdrom_spec.device.key = -1
cdrom_spec.device.backing = backing
cdrom_spec.device.connectable = connectable
config_spec = vim.vm.ConfigSpec(deviceChange=[cdrom_spec])
if boot_from_iso:
config_spec.bootOptions = vim.vm.BootOptions(
bootOrder=[vim.vm.BootOptions.BootableCdromDevice()]
)
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
return mounted
@mcp_tool(
name="inspect_ova",
description="Inspect an OVA (local path or URL): product, deployment configurations, networks, and disks",
annotations=ToolAnnotations(readOnlyHint=True),
)
def inspect_ova(self, ova_path: str, host: str | None = None) -> dict[str, Any]:
"""Inspect an OVA without deploying it.
Reads the OVF descriptor and reports the product, guest OS, hardware
version, selectable deployment configurations (e.g. Cisco S/M/L), the
networks the OVF expects, and its disks. Useful for picking a
``deployment_option`` and ``network`` before calling ``deploy_ova``.
Args:
ova_path: Local path to the .ova file, or an http(s) URL
host: Managed ESXi host to target (default: the default host)
Returns:
Dict describing the OVA
"""
conn = self._conn(host)
local_ova, is_temp = self._resolve_ova_file(ova_path, conn)
try:
with tarfile.open(local_ova) as tar:
ovf_member = next(
(m for m in tar.getmembers() if m.name.lower().endswith(".ovf")),
None,
)
if not ovf_member:
raise ValueError("No .ovf descriptor found in OVA")
ovf_xml = tar.extractfile(ovf_member).read().decode("utf-8")
disk_files = [
m.name for m in tar.getmembers() if m.name.lower().endswith(".vmdk")
]
finally:
if is_temp:
Path(local_ova).unlink(missing_ok=True)
def lname(tag: str) -> str:
return tag.rsplit("}", 1)[-1]
root = ET.fromstring(ovf_xml)
product: str | None = None
os_type: str | None = None
hw_version: str | None = None
configs: list[dict[str, Any]] = []
networks: list[str] = []
disks: list[dict[str, Any]] = []
for el in root.iter():
tag = lname(el.tag)
if tag == "Product" and product is None:
product = (el.text or "").strip()
elif tag == "OperatingSystemSection":
for key, val in el.attrib.items():
if lname(key) == "osType":
os_type = val
elif tag == "VirtualSystemType" and hw_version is None:
hw_version = (el.text or "").strip()
elif tag == "Configuration":
cid = None
default = False
for key, val in el.attrib.items():
if lname(key) == "id":
cid = val
elif lname(key) == "default":
default = val == "true"
label = ""
for child in el:
if lname(child.tag) == "Label":
label = (child.text or "").strip()
configs.append({"id": cid, "label": label, "default": default})
elif tag == "Network":
for key, val in el.attrib.items():
if lname(key) == "name":
networks.append(val)
elif tag == "Disk":
disk: dict[str, Any] = {}
for key, val in el.attrib.items():
name = lname(key)
if name == "diskId":
disk["disk_id"] = val
elif name == "capacity":
disk["capacity"] = val
elif name == "capacityAllocationUnits":
disk["units"] = val
disks.append(disk)
return {
"source": ova_path,
"product": product,
"os_type": os_type,
"hardware_version": hw_version,
"deployment_options": configs,
"networks": networks,
"disks": disks,
"disk_files": disk_files,
}
@mcp_tool(
name="export_vm_ovf",
description="Export a VM to OVF format on a datastore",
@ -729,7 +273,6 @@ class OVFManagementMixin(VSphereMixin):
vm_name: str,
target_path: str,
datastore: str | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Export a virtual machine to OVF format.
@ -737,13 +280,11 @@ class OVFManagementMixin(VSphereMixin):
vm_name: Name of the VM to export
target_path: Target directory path on datastore
datastore: Target datastore (default: VM's datastore)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with export details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -753,7 +294,7 @@ class OVFManagementMixin(VSphereMixin):
# Determine target datastore
if datastore:
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
ds_name = datastore
@ -771,7 +312,7 @@ class OVFManagementMixin(VSphereMixin):
raise ValueError(f"Export lease error: {lease.error}")
# Get OVF descriptor
ovf_manager = conn.content.ovfManager
ovf_manager = self.conn.content.ovfManager
ovf_descriptor = ovf_manager.CreateDescriptor(
obj=vm,
cdp=vim.OvfManager.CreateDescriptorParams(
@ -805,9 +346,7 @@ class OVFManagementMixin(VSphereMixin):
ovf_output_path = f"{target_path}/{ovf_filename}"
# Upload OVF descriptor to datastore
self._write_datastore_file(
ds_name, ovf_output_path, ovf_descriptor.ovfDescriptor, conn
)
self._write_datastore_file(ds_name, ovf_output_path, ovf_descriptor.ovfDescriptor)
exported_files.append(ovf_output_path)
@ -823,19 +362,17 @@ class OVFManagementMixin(VSphereMixin):
"ovf_descriptor": ovf_filename,
}
def _write_datastore_file(
self, datastore: str, path: str, content: str, conn
) -> None:
def _write_datastore_file(self, datastore: str, path: str, content: str) -> None:
"""Write a text file to datastore."""
dc_name = conn.datacenter.name
dc_name = self.conn.datacenter.name
url = (
f"https://{conn.settings.vcenter_host}/folder/{path}"
f"https://{self.conn.settings.vcenter_host}/folder/{path}"
f"?dcPath={dc_name}&dsName={datastore}"
)
# Setup request
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
if self.conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
@ -844,8 +381,8 @@ class OVFManagementMixin(VSphereMixin):
request.add_header("Content-Type", "application/xml")
request.add_header("Content-Length", str(len(data)))
if hasattr(conn.service_instance, "_stub"):
cookie = conn.service_instance._stub.cookie
if hasattr(self.conn.service_instance, "_stub"):
cookie = self.conn.service_instance._stub.cookie
if cookie:
request.add_header("Cookie", cookie)
@ -860,28 +397,25 @@ class OVFManagementMixin(VSphereMixin):
self,
ovf_path: str,
datastore: str,
host: str | None = None,
) -> list[dict[str, str]]:
"""List networks defined in an OVF descriptor.
Args:
ovf_path: Path to OVF file on datastore
datastore: Datastore containing the OVF
host: Managed ESXi host to target (default: the default host)
Returns:
List of network definitions
"""
conn = self._conn(host)
# Read OVF descriptor
ovf_descriptor = self._read_datastore_file(datastore, ovf_path, conn)
ovf_descriptor = self._read_datastore_file(datastore, ovf_path)
# Parse network references
ovf_manager = conn.content.ovfManager
ovf_manager = self.conn.content.ovfManager
# Get resource pool for parsing
host = None
for h in conn.datacenter.hostFolder.childEntity:
for h in self.conn.datacenter.hostFolder.childEntity:
if hasattr(h, "host"):
host = h.host[0] if h.host else None
break
@ -890,7 +424,7 @@ class OVFManagementMixin(VSphereMixin):
raise ValueError("No ESXi host found")
resource_pool = host.parent.resourcePool if hasattr(host, "parent") else None
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
# Create parse params to extract network info
import_spec_params = vim.OvfManager.CreateImportSpecParams()

54
src/mcvsphere/mixins/power_ops.py
View File

@ -2,28 +2,28 @@
from typing import TYPE_CHECKING
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class PowerOpsMixin(VSphereMixin):
class PowerOpsMixin(MCPMixin):
"""VM power management tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
@mcp_tool(
name="power_on",
description="Power on a virtual machine",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def power_on(self, name: str, host: str | None = None) -> str:
def power_on(self, name: str) -> str:
"""Power on a virtual machine."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -31,7 +31,7 @@ class PowerOpsMixin(VSphereMixin):
return f"VM '{name}' is already powered on"
task = vm.PowerOnVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' powered on"
@ -40,10 +40,9 @@ class PowerOpsMixin(VSphereMixin):
description="Power off a virtual machine (hard shutdown, like pulling the power cord)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def power_off(self, name: str, host: str | None = None) -> str:
def power_off(self, name: str) -> str:
"""Power off a virtual machine (hard shutdown)."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -51,7 +50,7 @@ class PowerOpsMixin(VSphereMixin):
return f"VM '{name}' is already powered off"
task = vm.PowerOffVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' powered off"
@ -60,10 +59,9 @@ class PowerOpsMixin(VSphereMixin):
description="Gracefully shutdown the guest OS (requires VMware Tools installed and running)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def shutdown_guest(self, name: str, host: str | None = None) -> str:
def shutdown_guest(self, name: str) -> str:
"""Gracefully shutdown the guest OS."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -84,10 +82,9 @@ class PowerOpsMixin(VSphereMixin):
description="Gracefully reboot the guest OS (requires VMware Tools)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False),
)
def reboot_guest(self, name: str, host: str | None = None) -> str:
def reboot_guest(self, name: str) -> str:
"""Gracefully reboot the guest OS."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -108,15 +105,14 @@ class PowerOpsMixin(VSphereMixin):
description="Reset (hard reboot) a virtual machine - like pressing the reset button",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False),
)
def reset_vm(self, name: str, host: str | None = None) -> str:
def reset_vm(self, name: str) -> str:
"""Reset (hard reboot) a virtual machine."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
task = vm.ResetVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' reset"
@ -125,10 +121,9 @@ class PowerOpsMixin(VSphereMixin):
description="Suspend a virtual machine (save state to disk)",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def suspend_vm(self, name: str, host: str | None = None) -> str:
def suspend_vm(self, name: str) -> str:
"""Suspend a virtual machine."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -139,7 +134,7 @@ class PowerOpsMixin(VSphereMixin):
return f"VM '{name}' is powered off, cannot suspend"
task = vm.SuspendVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' suspended"
@ -148,10 +143,9 @@ class PowerOpsMixin(VSphereMixin):
description="Put guest OS into standby mode (requires VMware Tools)",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def standby_guest(self, name: str, host: str | None = None) -> str:
def standby_guest(self, name: str) -> str:
"""Put guest OS into standby mode."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")

171
src/mcvsphere/mixins/resources.py
View File

@ -2,19 +2,20 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_resource, mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_resource, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class ResourcesMixin(VSphereMixin):
class ResourcesMixin(MCPMixin):
"""MCP Resources for vSphere infrastructure."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
# ─────────────────────────────────────────────────────────────────────────────
# Datastore File Browser (templated resource)
# ─────────────────────────────────────────────────────────────────────────────
@ -26,13 +27,13 @@ class ResourcesMixin(VSphereMixin):
)
def browse_datastore_root(self, datastore_name: str) -> list[dict[str, Any]]:
"""Browse files and folders at the root of a datastore."""
return self._browse_datastore_path(self.conn, datastore_name, "")
return self._browse_datastore_path(datastore_name, "")
def _browse_datastore_path(
self, conn, datastore_name: str, path: str
self, datastore_name: str, path: str
) -> list[dict[str, Any]]:
"""Browse files and folders on a datastore at a given path."""
ds = conn.find_datastore(datastore_name)
ds = self.conn.find_datastore(datastore_name)
if not ds:
raise ValueError(f"Datastore '{datastore_name}' not found")
@ -56,7 +57,7 @@ class ResourcesMixin(VSphereMixin):
# Search for files
task = browser.SearchDatastore_Task(ds_path, search_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
results = []
if task.info.result and task.info.result.file:
@ -85,7 +86,7 @@ class ResourcesMixin(VSphereMixin):
return sorted(results, key=lambda x: (x["type"] != "Folder", x["name"]))
def _stream_from_esxi(self, conn, datastore: str, path: str, chunk_size: int = 1024 * 1024):
def _stream_from_esxi(self, datastore: str, path: str, chunk_size: int = 1024 * 1024):
"""Generator that streams file content from ESXi datastore.
Yields raw bytes chunks as they arrive from ESXi HTTP API.
@ -95,13 +96,13 @@ class ResourcesMixin(VSphereMixin):
import urllib.request
from urllib.parse import quote
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
# Build download URL
dc_name = conn.datacenter.name
host = conn.settings.vcenter_host
dc_name = self.conn.datacenter.name
host = self.conn.settings.vcenter_host
encoded_path = quote(path, safe="")
url = (
@ -111,12 +112,12 @@ class ResourcesMixin(VSphereMixin):
# Create SSL context
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
if self.conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
# Get session cookie
stub = conn.si._stub
stub = self.conn.si._stub
cookie = stub.cookie
request = urllib.request.Request(url, method="GET")
@ -146,17 +147,15 @@ class ResourcesMixin(VSphereMixin):
annotations=ToolAnnotations(readOnlyHint=True),
)
def browse_datastore_tool(
self, datastore: str, path: str = "", host: str | None = None
self, datastore: str, path: str = ""
) -> list[dict[str, Any]]:
"""Browse files at a specific path on a datastore.
Args:
datastore: Datastore name (e.g., c1_ds-02)
path: Path within datastore (e.g., "rpm-desktop-1/" or "" for root)
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
return self._browse_datastore_path(conn, datastore, path)
return self._browse_datastore_path(datastore, path)
@mcp_tool(
name="download_from_datastore",
@ -169,7 +168,6 @@ class ResourcesMixin(VSphereMixin):
path: str,
save_to: str | None = None,
max_memory_mb: int = 50,
host: str | None = None,
) -> dict[str, Any]:
"""Download a file from a datastore using streaming.
@ -182,16 +180,14 @@ class ResourcesMixin(VSphereMixin):
path: Path to file on datastore (e.g., "iso/readme.txt")
save_to: Local path to save file (recommended for large files)
max_memory_mb: Max file size in MB to return in response (default 50MB)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with file content or save confirmation
"""
import base64
conn = self._conn(host)
max_bytes = max_memory_mb * 1024 * 1024
stream = self._stream_from_esxi(conn, datastore, path)
stream = self._stream_from_esxi(datastore, path)
# First yield is total size (or None)
total_size = next(stream)
@ -265,7 +261,6 @@ class ResourcesMixin(VSphereMixin):
local_path: str | None = None,
content_base64: str | None = None,
chunk_size: int = 8 * 1024 * 1024, # 8MB chunks
host: str | None = None,
) -> dict[str, Any]:
"""Upload a file to a datastore.
@ -278,7 +273,6 @@ class ResourcesMixin(VSphereMixin):
local_path: Local file path to upload - streams from disk (preferred for large files)
content_base64: Base64-encoded file content (for small files only)
chunk_size: Chunk size for streaming uploads (default 8MB)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with upload details including size and whether streaming was used
@ -288,37 +282,35 @@ class ResourcesMixin(VSphereMixin):
import ssl
import urllib.request
conn = self._conn(host)
if not local_path and not content_base64:
raise ValueError("Either local_path or content_base64 must be provided")
if local_path and content_base64:
raise ValueError("Only one of local_path or content_base64 can be provided")
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
# Build upload URL
dc_name = conn.datacenter.name
vc_host = conn.settings.vcenter_host
dc_name = self.conn.datacenter.name
host = self.conn.settings.vcenter_host
from urllib.parse import quote
encoded_path = quote(remote_path, safe="")
url = (
f"https://{vc_host}/folder/{encoded_path}"
f"https://{host}/folder/{encoded_path}"
f"?dcPath={quote(dc_name)}&dsName={quote(datastore)}"
)
# Create SSL context
context = ssl.create_default_context()
if conn.settings.vcenter_insecure:
if self.conn.settings.vcenter_insecure:
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
# Get session cookie from existing connection
stub = conn.si._stub
stub = self.conn.si._stub
cookie = stub.cookie
if local_path:
@ -407,21 +399,17 @@ class ResourcesMixin(VSphereMixin):
description="Delete a file or folder from a datastore",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def delete_datastore_file(
self, datastore: str, path: str, host: str | None = None
) -> str:
def delete_datastore_file(self, datastore: str, path: str) -> str:
"""Delete a file or folder from a datastore.
Args:
datastore: Datastore name
path: Path to file or folder to delete (e.g., "iso/old-file.iso")
host: Managed ESXi host to target (default: the default host)
Returns:
Success message
"""
conn = self._conn(host)
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
@ -429,11 +417,11 @@ class ResourcesMixin(VSphereMixin):
ds_path = f"[{datastore}] {path}"
# Use FileManager to delete
file_manager = conn.content.fileManager
dc = conn.datacenter
file_manager = self.conn.content.fileManager
dc = self.conn.datacenter
task = file_manager.DeleteDatastoreFile_Task(name=ds_path, datacenter=dc)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"Deleted [{datastore}] {path}"
@ -442,21 +430,17 @@ class ResourcesMixin(VSphereMixin):
description="Create a folder on a datastore",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def create_datastore_folder(
self, datastore: str, path: str, host: str | None = None
) -> str:
def create_datastore_folder(self, datastore: str, path: str) -> str:
"""Create a folder on a datastore.
Args:
datastore: Datastore name
path: Folder path to create (e.g., "iso/new-folder")
host: Managed ESXi host to target (default: the default host)
Returns:
Success message
"""
conn = self._conn(host)
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
@ -464,8 +448,8 @@ class ResourcesMixin(VSphereMixin):
ds_path = f"[{datastore}] {path}"
# Use FileManager to create directory
file_manager = conn.content.fileManager
file_manager.MakeDirectory(name=ds_path, datacenter=conn.datacenter)
file_manager = self.conn.content.fileManager
file_manager.MakeDirectory(name=ds_path, datacenter=self.conn.datacenter)
return f"Created folder [{datastore}] {path}"
@ -490,7 +474,6 @@ class ResourcesMixin(VSphereMixin):
source_path: str,
dest_datastore: str | None = None,
dest_path: str | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Move or rename a file or folder on a datastore.
@ -499,13 +482,11 @@ class ResourcesMixin(VSphereMixin):
source_path: Source path (e.g., "iso/old-name.iso")
dest_datastore: Destination datastore (default: same as source)
dest_path: Destination path (default: same as source with new name)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with move operation details
"""
conn = self._conn(host)
ds = conn.find_datastore(source_datastore)
ds = self.conn.find_datastore(source_datastore)
if not ds:
raise ValueError(f"Datastore '{source_datastore}' not found")
@ -513,7 +494,7 @@ class ResourcesMixin(VSphereMixin):
if not dest_datastore:
dest_datastore = source_datastore
else:
dest_ds = conn.find_datastore(dest_datastore)
dest_ds = self.conn.find_datastore(dest_datastore)
if not dest_ds:
raise ValueError(f"Destination datastore '{dest_datastore}' not found")
@ -525,8 +506,8 @@ class ResourcesMixin(VSphereMixin):
dest_ds_path = f"[{dest_datastore}] {dest_path}"
# Use FileManager to move
file_manager = conn.content.fileManager
dc = conn.datacenter
file_manager = self.conn.content.fileManager
dc = self.conn.datacenter
task = file_manager.MoveDatastoreFile_Task(
sourceName=source_ds_path,
@ -535,7 +516,7 @@ class ResourcesMixin(VSphereMixin):
destinationDatacenter=dc,
force=False,
)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"action": "moved",
@ -555,7 +536,6 @@ class ResourcesMixin(VSphereMixin):
dest_datastore: str | None = None,
dest_path: str | None = None,
force: bool = False,
host: str | None = None,
) -> dict[str, Any]:
"""Copy a file or folder on a datastore.
@ -565,13 +545,11 @@ class ResourcesMixin(VSphereMixin):
dest_datastore: Destination datastore (default: same as source)
dest_path: Destination path (required)
force: Overwrite destination if exists (default False)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with copy operation details
"""
conn = self._conn(host)
ds = conn.find_datastore(source_datastore)
ds = self.conn.find_datastore(source_datastore)
if not ds:
raise ValueError(f"Datastore '{source_datastore}' not found")
@ -579,7 +557,7 @@ class ResourcesMixin(VSphereMixin):
if not dest_datastore:
dest_datastore = source_datastore
else:
dest_ds = conn.find_datastore(dest_datastore)
dest_ds = self.conn.find_datastore(dest_datastore)
if not dest_ds:
raise ValueError(f"Destination datastore '{dest_datastore}' not found")
@ -591,8 +569,8 @@ class ResourcesMixin(VSphereMixin):
dest_ds_path = f"[{dest_datastore}] {dest_path}"
# Use FileManager to copy
file_manager = conn.content.fileManager
dc = conn.datacenter
file_manager = self.conn.content.fileManager
dc = self.conn.datacenter
task = file_manager.CopyDatastoreFile_Task(
sourceName=source_ds_path,
@ -601,7 +579,7 @@ class ResourcesMixin(VSphereMixin):
destinationDatacenter=dc,
force=force,
)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"action": "copied",
@ -741,15 +719,9 @@ class ResourcesMixin(VSphereMixin):
description="Get detailed information about a specific datastore",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_datastore_info(self, name: str, host: str | None = None) -> dict[str, Any]:
"""Get detailed datastore information.
Args:
name: Datastore name
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
ds = conn.find_datastore(name)
def get_datastore_info(self, name: str) -> dict[str, Any]:
"""Get detailed datastore information."""
ds = self.conn.find_datastore(name)
if not ds:
raise ValueError(f"Datastore '{name}' not found")
@ -781,15 +753,9 @@ class ResourcesMixin(VSphereMixin):
description="Get detailed information about a specific network",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_network_info(self, name: str, host: str | None = None) -> dict[str, Any]:
"""Get detailed network information.
Args:
name: Network name
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
net = conn.find_network(name)
def get_network_info(self, name: str) -> dict[str, Any]:
"""Get detailed network information."""
net = self.conn.find_network(name)
if not net:
raise ValueError(f"Network '{name}' not found")
@ -818,21 +784,14 @@ class ResourcesMixin(VSphereMixin):
description="Get information about resource pools",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_resource_pool_info(
self, name: str | None = None, host: str | None = None
) -> dict[str, Any]:
def get_resource_pool_info(self, name: str | None = None) -> dict[str, Any]:
"""Get resource pool information.
If name is not provided, returns info for the default resource pool.
Args:
name: Resource pool name (default: the default resource pool)
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
if name:
container = conn.content.viewManager.CreateContainerView(
conn.content.rootFolder, [vim.ResourcePool], True
container = self.conn.content.viewManager.CreateContainerView(
self.conn.content.rootFolder, [vim.ResourcePool], True
)
try:
pool = next((p for p in container.view if p.name == name), None)
@ -841,7 +800,7 @@ class ResourcesMixin(VSphereMixin):
if not pool:
raise ValueError(f"Resource pool '{name}' not found")
else:
pool = conn.resource_pool
pool = self.conn.resource_pool
runtime = pool.summary.runtime
config = pool.summary.config
@ -864,15 +823,10 @@ class ResourcesMixin(VSphereMixin):
description="List all VM templates in the inventory",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_templates(self, host: str | None = None) -> list[dict[str, Any]]:
"""List all VM templates.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
def list_templates(self) -> list[dict[str, Any]]:
"""List all VM templates."""
templates = []
for vm in conn.get_all_vms():
for vm in self.conn.get_all_vms():
if vm.config and vm.config.template:
templates.append(
{
@ -889,14 +843,9 @@ class ResourcesMixin(VSphereMixin):
description="Get vCenter/ESXi server information",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_vcenter_info(self, host: str | None = None) -> dict[str, Any]:
"""Get vCenter/ESXi server information.
Args:
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
about = conn.content.about
def get_vcenter_info(self) -> dict[str, Any]:
"""Get vCenter/ESXi server information."""
about = self.conn.content.about
return {
"name": about.name,
"full_name": about.fullName,

58
src/mcvsphere/mixins/serial_port.py
View File

@ -5,17 +5,15 @@ import socket
import time
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class SerialPortMixin(VSphereMixin):
class SerialPortMixin(MCPMixin):
"""Serial port management for VM network console access.
Network serial ports allow telnet/TCP connections to VM consoles,
@ -28,6 +26,9 @@ class SerialPortMixin(VSphereMixin):
- tcp+ssl: Encrypted SSL over TCP
"""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _get_serial_port(self, vm: vim.VirtualMachine) -> vim.vm.device.VirtualSerialPort | None:
"""Find existing serial port with URI backing on a VM."""
if not vm.config:
@ -66,18 +67,16 @@ class SerialPortMixin(VSphereMixin):
description="Get current serial port configuration for a VM",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_serial_port(self, name: str, host: str | None = None) -> dict[str, Any]:
def get_serial_port(self, name: str) -> dict[str, Any]:
"""Get serial port configuration.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with serial port details or message if not configured
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -111,7 +110,6 @@ class SerialPortMixin(VSphereMixin):
port: int | None = None,
direction: str = "server",
yield_on_poll: bool = True,
host: str | None = None,
) -> dict[str, Any]:
"""Setup or update network serial port.
@ -121,13 +119,11 @@ class SerialPortMixin(VSphereMixin):
port: TCP port number. If not specified, auto-assigns unused port.
direction: 'server' (VM listens) or 'client' (VM connects). Default: server
yield_on_poll: Enable CPU yield behavior. Default: True
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with configured serial port URI and details
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -146,8 +142,8 @@ class SerialPortMixin(VSphereMixin):
# Find or assign port
if port is None:
vm_host = vm.runtime.host
host_ip = vm_host.name if vm_host else conn.settings.vcenter_host
host = vm.runtime.host
host_ip = host.name if host else self.conn.settings.vcenter_host
port = self._find_unused_port(host_ip)
# Build service URI
@ -182,11 +178,11 @@ class SerialPortMixin(VSphereMixin):
spec = vim.vm.ConfigSpec()
spec.deviceChange = [serial_spec]
task = vm.ReconfigVM_Task(spec=spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
# Get ESXi host info for connection string
vm_host = vm.runtime.host
host_ip = vm_host.name if vm_host else conn.settings.vcenter_host
host = vm.runtime.host
host_ip = host.name if host else self.conn.settings.vcenter_host
return {
"vm_name": name,
@ -204,19 +200,17 @@ class SerialPortMixin(VSphereMixin):
description="Connect or disconnect an existing serial port on a VM",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def connect_serial_port(self, name: str, connected: bool = True, host: str | None = None) -> dict[str, Any]:
def connect_serial_port(self, name: str, connected: bool = True) -> dict[str, Any]:
"""Connect or disconnect serial port.
Args:
name: VM name
connected: True to connect, False to disconnect. Default: True
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with result
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -233,7 +227,7 @@ class SerialPortMixin(VSphereMixin):
spec = vim.vm.ConfigSpec()
spec.deviceChange = [serial_spec]
task = vm.ReconfigVM_Task(spec=spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm_name": name,
@ -246,20 +240,18 @@ class SerialPortMixin(VSphereMixin):
description="Reset serial port by disconnecting and reconnecting (clears stuck connections)",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def clear_serial_port(self, name: str, host: str | None = None) -> dict[str, Any]:
def clear_serial_port(self, name: str) -> dict[str, Any]:
"""Clear serial port by cycling connection state.
Useful for clearing stuck or stale connections.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with result
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -268,11 +260,11 @@ class SerialPortMixin(VSphereMixin):
raise ValueError(f"No network serial port configured on VM '{name}'")
# Disconnect
self.connect_serial_port(name, connected=False, host=host)
self.connect_serial_port(name, connected=False)
time.sleep(1)
# Reconnect
self.connect_serial_port(name, connected=True, host=host)
self.connect_serial_port(name, connected=True)
return {
"vm_name": name,
@ -286,18 +278,16 @@ class SerialPortMixin(VSphereMixin):
description="Remove the network serial port from a VM. VM must be powered off.",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def remove_serial_port(self, name: str, host: str | None = None) -> str:
def remove_serial_port(self, name: str) -> str:
"""Remove serial port from VM.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
Returns:
Success message
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -317,6 +307,6 @@ class SerialPortMixin(VSphereMixin):
spec = vim.vm.ConfigSpec()
spec.deviceChange = [serial_spec]
task = vm.ReconfigVM_Task(spec=spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"Serial port removed from VM '{name}'"

101
src/mcvsphere/mixins/snapshots.py
View File

@ -2,19 +2,20 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class SnapshotsMixin(VSphereMixin):
class SnapshotsMixin(MCPMixin):
"""VM snapshot management tools."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
def _get_snapshot_tree(
self, snapshots: list, parent_path: str = ""
) -> list[dict[str, Any]]:
@ -55,15 +56,9 @@ class SnapshotsMixin(VSphereMixin):
description="List all snapshots for a virtual machine",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_snapshots(self, name: str, host: str | None = None) -> list[dict[str, Any]]:
"""List all snapshots for a VM.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def list_snapshots(self, name: str) -> list[dict[str, Any]]:
"""List all snapshots for a VM."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -101,7 +96,6 @@ class SnapshotsMixin(VSphereMixin):
description: str = "",
memory: bool = True,
quiesce: bool = False,
host: str | None = None,
) -> str:
"""Create a VM snapshot.
@ -111,10 +105,8 @@ class SnapshotsMixin(VSphereMixin):
description: Optional description
memory: Include memory state (allows instant restore to running state)
quiesce: Quiesce guest filesystem (requires VMware Tools, ensures consistent state)
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -135,7 +127,7 @@ class SnapshotsMixin(VSphereMixin):
memory=memory,
quiesce=quiesce,
)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"Snapshot '{snapshot_name}' created for VM '{name}'"
@ -144,18 +136,9 @@ class SnapshotsMixin(VSphereMixin):
description="Revert a VM to a specific snapshot",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False),
)
def revert_to_snapshot(
self, name: str, snapshot_name: str, host: str | None = None
) -> str:
"""Revert VM to a specific snapshot.
Args:
name: VM name
snapshot_name: Name of snapshot to revert to
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def revert_to_snapshot(self, name: str, snapshot_name: str) -> str:
"""Revert VM to a specific snapshot."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -169,7 +152,7 @@ class SnapshotsMixin(VSphereMixin):
raise ValueError(f"Snapshot '{snapshot_name}' not found on VM '{name}'")
task = snapshot.RevertToSnapshot_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' reverted to snapshot '{snapshot_name}'"
@ -178,15 +161,9 @@ class SnapshotsMixin(VSphereMixin):
description="Revert a VM to its current (most recent) snapshot",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False),
)
def revert_to_current_snapshot(self, name: str, host: str | None = None) -> str:
"""Revert VM to its current snapshot.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def revert_to_current_snapshot(self, name: str) -> str:
"""Revert VM to its current snapshot."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -194,7 +171,7 @@ class SnapshotsMixin(VSphereMixin):
raise ValueError(f"VM '{name}' has no current snapshot")
task = vm.RevertToCurrentSnapshot_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' reverted to current snapshot"
@ -204,11 +181,7 @@ class SnapshotsMixin(VSphereMixin):
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def delete_snapshot(
self,
name: str,
snapshot_name: str,
remove_children: bool = False,
host: str | None = None,
self, name: str, snapshot_name: str, remove_children: bool = False
) -> str:
"""Delete a VM snapshot.
@ -216,10 +189,8 @@ class SnapshotsMixin(VSphereMixin):
name: VM name
snapshot_name: Name of snapshot to delete
remove_children: If True, also delete child snapshots
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -233,7 +204,7 @@ class SnapshotsMixin(VSphereMixin):
raise ValueError(f"Snapshot '{snapshot_name}' not found on VM '{name}'")
task = snapshot.RemoveSnapshot_Task(removeChildren=remove_children)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
msg = f"Snapshot '{snapshot_name}' deleted from VM '{name}'"
if remove_children:
@ -245,15 +216,9 @@ class SnapshotsMixin(VSphereMixin):
description="Delete ALL snapshots from a VM (consolidates disk)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def delete_all_snapshots(self, name: str, host: str | None = None) -> str:
"""Delete all snapshots from a VM.
Args:
name: VM name
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def delete_all_snapshots(self, name: str) -> str:
"""Delete all snapshots from a VM."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -261,7 +226,7 @@ class SnapshotsMixin(VSphereMixin):
return f"VM '{name}' has no snapshots to delete"
task = vm.RemoveAllSnapshots_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"All snapshots deleted from VM '{name}'"
@ -276,19 +241,9 @@ class SnapshotsMixin(VSphereMixin):
snapshot_name: str,
new_name: str | None = None,
new_description: str | None = None,
host: str | None = None,
) -> str:
"""Rename a snapshot or update its description.
Args:
name: VM name
snapshot_name: Name of snapshot to rename
new_name: New name for the snapshot
new_description: New description for the snapshot
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
"""Rename a snapshot or update its description."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")

139
src/mcvsphere/mixins/vcenter_ops.py
View File

@ -3,31 +3,19 @@
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class VCenterOpsMixin(VSphereMixin):
class VCenterOpsMixin(MCPMixin):
"""vCenter-specific operations (require vCenter, not just ESXi)."""
@mcp_tool(
name="list_servers",
description="List the ESXi hosts this server manages. Pass a host's value as the 'host' argument to other tools to target it.",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_servers(self) -> list[dict[str, Any]]:
"""List managed ESXi hosts and their connection status.
The ``host`` field is the identifier to pass as the ``host`` argument on
host-aware tools; omitting it targets the ``default`` host.
"""
return self.manager.describe()
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
# ─────────────────────────────────────────────────────────────────────────────
# Storage vMotion (works even on single-host vCenter)
@ -43,7 +31,6 @@ class VCenterOpsMixin(VSphereMixin):
vm_name: str,
target_datastore: str,
thin_provision: bool | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Move a VM's storage to a different datastore.
@ -54,17 +41,15 @@ class VCenterOpsMixin(VSphereMixin):
vm_name: Name of the VM to migrate
target_datastore: Target datastore name
thin_provision: Convert to thin provisioning (None = keep current)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with migration details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
ds = conn.find_datastore(target_datastore)
ds = self.conn.find_datastore(target_datastore)
if not ds:
raise ValueError(f"Datastore '{target_datastore}' not found")
@ -91,7 +76,7 @@ class VCenterOpsMixin(VSphereMixin):
# Perform the relocation
task = vm.RelocateVM_Task(spec=relocate_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -111,7 +96,6 @@ class VCenterOpsMixin(VSphereMixin):
vm_name: str,
disk_label: str,
target_datastore: str,
host: str | None = None,
) -> dict[str, Any]:
"""Move a specific VM disk to a different datastore.
@ -119,17 +103,15 @@ class VCenterOpsMixin(VSphereMixin):
vm_name: Name of the VM
disk_label: Label of the disk (e.g., 'Hard disk 1')
target_datastore: Target datastore name
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with migration details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
ds = conn.find_datastore(target_datastore)
ds = self.conn.find_datastore(target_datastore)
if not ds:
raise ValueError(f"Datastore '{target_datastore}' not found")
@ -163,7 +145,7 @@ class VCenterOpsMixin(VSphereMixin):
# Perform the relocation
task = vm.RelocateVM_Task(spec=relocate_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -182,7 +164,7 @@ class VCenterOpsMixin(VSphereMixin):
description="Convert a VM to a template (idempotent - safe to call on existing template)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def convert_to_template(self, vm_name: str, host: str | None = None) -> dict[str, Any]:
def convert_to_template(self, vm_name: str) -> dict[str, Any]:
"""Convert a VM to a template.
The VM must be powered off. Once converted, it cannot be powered on
@ -190,13 +172,11 @@ class VCenterOpsMixin(VSphereMixin):
Args:
vm_name: Name of the VM to convert
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with conversion details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
@ -227,20 +207,17 @@ class VCenterOpsMixin(VSphereMixin):
self,
template_name: str,
resource_pool: str | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Convert a template back to a regular VM.
Args:
template_name: Name of the template
resource_pool: Resource pool for the VM (optional)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with conversion details
"""
conn = self._conn(host)
vm = conn.find_vm(template_name)
vm = self.conn.find_vm(template_name)
if not vm:
raise ValueError(f"Template '{template_name}' not found")
@ -253,20 +230,20 @@ class VCenterOpsMixin(VSphereMixin):
# Get resource pool
if resource_pool:
pool = self._find_resource_pool(resource_pool, conn)
pool = self._find_resource_pool(resource_pool)
if not pool:
raise ValueError(f"Resource pool '{resource_pool}' not found")
else:
pool = conn.resource_pool
pool = self.conn.resource_pool
# Get a host from the resource pool
target_host = None
host = None
if hasattr(pool, "owner") and hasattr(pool.owner, "host"):
hosts = pool.owner.host
if hosts:
target_host = hosts[0]
host = hosts[0]
vm.MarkAsVirtualMachine(pool=pool, host=target_host)
vm.MarkAsVirtualMachine(pool=pool, host=host)
return {
"vm": template_name,
@ -274,10 +251,10 @@ class VCenterOpsMixin(VSphereMixin):
"is_template": False,
}
def _find_resource_pool(self, name: str, conn) -> vim.ResourcePool | None:
def _find_resource_pool(self, name: str) -> vim.ResourcePool | None:
"""Find a resource pool by name."""
container = conn.content.viewManager.CreateContainerView(
conn.content.rootFolder, [vim.ResourcePool], True
container = self.conn.content.viewManager.CreateContainerView(
self.conn.content.rootFolder, [vim.ResourcePool], True
)
try:
for pool in container.view:
@ -298,7 +275,6 @@ class VCenterOpsMixin(VSphereMixin):
new_vm_name: str,
datastore: str | None = None,
power_on: bool = False,
host: str | None = None,
) -> dict[str, Any]:
"""Deploy a new VM from a template.
@ -307,13 +283,11 @@ class VCenterOpsMixin(VSphereMixin):
new_vm_name: Name for the new VM
datastore: Target datastore (default: same as template)
power_on: Power on after deployment (default False)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with deployment details
"""
conn = self._conn(host)
template = conn.find_vm(template_name)
template = self.conn.find_vm(template_name)
if not template:
raise ValueError(f"Template '{template_name}' not found")
@ -321,15 +295,15 @@ class VCenterOpsMixin(VSphereMixin):
raise ValueError(f"'{template_name}' is not a template")
# Check if target VM already exists
if conn.find_vm(new_vm_name):
if self.conn.find_vm(new_vm_name):
raise ValueError(f"VM '{new_vm_name}' already exists")
# Build clone spec
relocate_spec = vim.vm.RelocateSpec()
relocate_spec.pool = conn.resource_pool
relocate_spec.pool = self.conn.resource_pool
if datastore:
ds = conn.find_datastore(datastore)
ds = self.conn.find_datastore(datastore)
if not ds:
raise ValueError(f"Datastore '{datastore}' not found")
relocate_spec.datastore = ds
@ -340,14 +314,14 @@ class VCenterOpsMixin(VSphereMixin):
clone_spec.template = False # Create VM, not another template
# Get target folder
folder = conn.datacenter.vmFolder
folder = self.conn.datacenter.vmFolder
# Clone the template
task = template.Clone(folder=folder, name=new_vm_name, spec=clone_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
# Get the new VM info
new_vm = conn.find_vm(new_vm_name)
new_vm = self.conn.find_vm(new_vm_name)
return {
"vm": new_vm_name,
@ -366,16 +340,12 @@ class VCenterOpsMixin(VSphereMixin):
description="List VM folders in the datacenter",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_folders(self, host: str | None = None) -> list[dict[str, Any]]:
def list_folders(self) -> list[dict[str, Any]]:
"""List all VM folders in the datacenter.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
List of folder details
"""
conn = self._conn(host)
folders = []
def _collect_folders(folder: vim.Folder, path: str = ""):
@ -393,7 +363,7 @@ class VCenterOpsMixin(VSphereMixin):
_collect_folders(child, current_path)
# Start from VM folder
vm_folder = conn.datacenter.vmFolder
vm_folder = self.conn.datacenter.vmFolder
_collect_folders(vm_folder)
return folders
@ -407,25 +377,22 @@ class VCenterOpsMixin(VSphereMixin):
self,
folder_name: str,
parent_path: str | None = None,
host: str | None = None,
) -> dict[str, Any]:
"""Create a new VM folder.
Args:
folder_name: Name for the new folder
parent_path: Path to parent folder (None = root vm folder)
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with folder details
"""
conn = self._conn(host)
if parent_path:
parent = self._find_folder_by_path(parent_path, conn)
parent = self._find_folder_by_path(parent_path)
if not parent:
raise ValueError(f"Parent folder '{parent_path}' not found")
else:
parent = conn.datacenter.vmFolder
parent = self.conn.datacenter.vmFolder
parent.CreateFolder(name=folder_name)
@ -436,11 +403,11 @@ class VCenterOpsMixin(VSphereMixin):
"path": f"{parent_path}/{folder_name}" if parent_path else f"vm/{folder_name}",
}
def _find_folder_by_path(self, path: str, conn) -> vim.Folder | None:
def _find_folder_by_path(self, path: str) -> vim.Folder | None:
"""Find a folder by its path (e.g., 'vm/Production/WebServers')."""
parts = [p for p in path.split("/") if p and p != "vm"]
current = conn.datacenter.vmFolder
current = self.conn.datacenter.vmFolder
for part in parts:
found = None
if hasattr(current, "childEntity"):
@ -463,24 +430,21 @@ class VCenterOpsMixin(VSphereMixin):
self,
vm_name: str,
folder_path: str,
host: str | None = None,
) -> dict[str, Any]:
"""Move a VM to a different folder.
Args:
vm_name: Name of the VM to move
folder_path: Path to target folder
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with move details
"""
conn = self._conn(host)
vm = conn.find_vm(vm_name)
vm = self.conn.find_vm(vm_name)
if not vm:
raise ValueError(f"VM '{vm_name}' not found")
folder = self._find_folder_by_path(folder_path, conn)
folder = self._find_folder_by_path(folder_path)
if not folder:
raise ValueError(f"Folder '{folder_path}' not found")
@ -489,7 +453,7 @@ class VCenterOpsMixin(VSphereMixin):
# Move the VM
task = folder.MoveIntoFolder_Task([vm])
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return {
"vm": vm_name,
@ -511,20 +475,17 @@ class VCenterOpsMixin(VSphereMixin):
self,
max_count: int = 20,
entity_name: str | None = None,
host: str | None = None,
) -> list[dict[str, Any]]:
"""List recent tasks from vCenter.
Args:
max_count: Maximum number of tasks to return (default 20)
entity_name: Filter by entity name (optional)
host: Managed ESXi host to target (default: the default host)
Returns:
List of task details
"""
conn = self._conn(host)
task_manager = conn.content.taskManager
task_manager = self.conn.content.taskManager
recent_tasks = task_manager.recentTask
tasks = []
@ -570,7 +531,6 @@ class VCenterOpsMixin(VSphereMixin):
max_count: int = 50,
event_types: list[str] | None = None,
hours_back: int = 24,
host: str | None = None,
) -> list[dict[str, Any]]:
"""List recent events from vCenter.
@ -578,13 +538,11 @@ class VCenterOpsMixin(VSphereMixin):
max_count: Maximum number of events (default 50)
event_types: Filter by event type names (optional)
hours_back: How many hours back to look (default 24)
host: Managed ESXi host to target (default: the default host)
Returns:
List of event details
"""
conn = self._conn(host)
event_manager = conn.content.eventManager
event_manager = self.conn.content.eventManager
# Create filter spec
filter_spec = vim.event.EventFilterSpec()
@ -635,19 +593,15 @@ class VCenterOpsMixin(VSphereMixin):
description="List all clusters in the datacenter",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_clusters(self, host: str | None = None) -> list[dict[str, Any]]:
def list_clusters(self) -> list[dict[str, Any]]:
"""List all clusters in the datacenter.
Args:
host: Managed ESXi host to target (default: the default host)
Returns:
List of cluster details with DRS/HA status
"""
conn = self._conn(host)
clusters = []
for entity in conn.datacenter.hostFolder.childEntity:
for entity in self.conn.datacenter.hostFolder.childEntity:
if isinstance(entity, vim.ClusterComputeResource):
drs_config = entity.configuration.drsConfig
ha_config = entity.configuration.dasConfig
@ -686,19 +640,16 @@ class VCenterOpsMixin(VSphereMixin):
def get_drs_recommendations(
self,
cluster_name: str,
host: str | None = None,
) -> list[dict[str, Any]]:
"""Get DRS recommendations for a cluster.
Args:
cluster_name: Name of the cluster
host: Managed ESXi host to target (default: the default host)
Returns:
List of DRS recommendations
"""
conn = self._conn(host)
cluster = self._find_cluster(cluster_name, conn)
cluster = self._find_cluster(cluster_name)
if not cluster:
raise ValueError(f"Cluster '{cluster_name}' not found")
@ -738,9 +689,9 @@ class VCenterOpsMixin(VSphereMixin):
return recommendations
def _find_cluster(self, name: str, conn) -> vim.ClusterComputeResource | None:
def _find_cluster(self, name: str) -> vim.ClusterComputeResource | None:
"""Find a cluster by name."""
for entity in conn.datacenter.hostFolder.childEntity:
for entity in self.conn.datacenter.hostFolder.childEntity:
if isinstance(entity, vim.ClusterComputeResource) and entity.name == name:
return entity
return None

214
src/mcvsphere/mixins/vm_lifecycle.py
View File

@ -2,34 +2,29 @@
from typing import TYPE_CHECKING, Any
from fastmcp.contrib.mcp_mixin import mcp_tool
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from mcp.types import ToolAnnotations
from pyVmomi import vim
from mcvsphere.mixins._base import VSphereMixin
if TYPE_CHECKING:
pass
from mcvsphere.connection import VMwareConnection
class VMLifecycleMixin(VSphereMixin):
class VMLifecycleMixin(MCPMixin):
"""VM lifecycle management tools - CRUD operations for virtual machines."""
def __init__(self, conn: "VMwareConnection"):
self.conn = conn
@mcp_tool(
name="list_vms",
description="List all virtual machines in the vSphere inventory",
annotations=ToolAnnotations(readOnlyHint=True),
)
def list_vms(self, host: str | None = None) -> list[dict[str, Any]]:
"""List all virtual machines with basic info.
Args:
host: Managed ESXi host to query (default: the default host).
Use list_servers to see available hosts.
"""
conn = self._conn(host)
def list_vms(self) -> list[dict[str, Any]]:
"""List all virtual machines with basic info."""
vms = []
for vm in conn.get_all_vms():
for vm in self.conn.get_all_vms():
vms.append(
{
"name": vm.name,
@ -46,15 +41,9 @@ class VMLifecycleMixin(VSphereMixin):
description="Get detailed information about a specific virtual machine",
annotations=ToolAnnotations(readOnlyHint=True),
)
def get_vm_info(self, name: str, host: str | None = None) -> dict[str, Any]:
"""Get detailed VM information including hardware, network, and storage.
Args:
name: VM name
host: Managed ESXi host to query (default: the default host)
"""
conn = self._conn(host)
vm = conn.find_vm(name)
def get_vm_info(self, name: str) -> dict[str, Any]:
"""Get detailed VM information including hardware, network, and storage."""
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -110,7 +99,7 @@ class VMLifecycleMixin(VSphereMixin):
@mcp_tool(
name="create_vm",
description="Create a new virtual machine with specified resources and a CD/DVD drive (optionally booting from an ISO)",
description="Create a new virtual machine with specified resources",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=False),
)
def create_vm(
@ -122,42 +111,19 @@ class VMLifecycleMixin(VSphereMixin):
datastore: str | None = None,
network: str | None = None,
guest_id: str = "otherGuest64",
iso_path: str | None = None,
iso_datastore: str | None = None,
boot_from_iso: bool = True,
host: str | None = None,
) -> str:
"""Create a new virtual machine with specified configuration.
The VM always gets a CD/DVD drive. If ``iso_path`` is given, the drive
is backed by that ISO and connected at power-on; otherwise it is an
empty client device (so ``attach_iso`` can mount media later).
Args:
name: VM name
cpu: vCPU count
memory_mb: Memory in MB
disk_gb: Primary disk size in GB
datastore: Datastore for the VM (default: largest available)
network: Port group for the NIC (default: configured network)
guest_id: vSphere guest OS identifier
iso_path: ISO path on a datastore (e.g. 'iso/ubuntu.iso') to mount in the CD/DVD drive
iso_datastore: Datastore holding the ISO (default: the VM's datastore)
boot_from_iso: When an ISO is given, put the CD/DVD first in the boot order
host: Managed ESXi host to target (default: the default host)
"""
conn = self._conn(host)
"""Create a new virtual machine with specified configuration."""
# Resolve datastore
datastore_obj = conn.datastore
datastore_obj = self.conn.datastore
if datastore:
datastore_obj = conn.find_datastore(datastore)
datastore_obj = self.conn.find_datastore(datastore)
if not datastore_obj:
raise ValueError(f"Datastore '{datastore}' not found")
# Resolve network
network_obj = conn.network
network_obj = self.conn.network
if network:
network_obj = conn.find_network(network)
network_obj = self.conn.find_network(network)
if not network_obj:
raise ValueError(f"Network '{network}' not found")
@ -229,47 +195,13 @@ class VMLifecycleMixin(VSphereMixin):
)
device_specs.append(nic_spec)
# Add a CD/DVD drive on the default IDE controller (vSphere auto-creates
# IDE controller key 200). Backed by an ISO if one was requested,
# otherwise an empty client device so media can be mounted later.
cdrom_spec = vim.vm.device.VirtualDeviceSpec()
cdrom_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
cdrom_spec.device = vim.vm.device.VirtualCdrom()
cdrom_spec.device.controllerKey = 200
cdrom_spec.device.unitNumber = 0
cdrom_spec.device.key = -2
connectable = vim.vm.device.VirtualDevice.ConnectInfo()
connectable.allowGuestControl = True
connectable.connected = False
if iso_path:
iso_ds = iso_datastore or datastore_obj.name
backing = vim.vm.device.VirtualCdrom.IsoBackingInfo()
backing.fileName = f"[{iso_ds}] {iso_path}"
connectable.startConnected = True
else:
backing = vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo()
backing.deviceName = ""
backing.exclusive = False
connectable.startConnected = False
cdrom_spec.device.backing = backing
cdrom_spec.device.connectable = connectable
device_specs.append(cdrom_spec)
# Boot from the CD/DVD first when installing from an ISO
if iso_path and boot_from_iso:
vm_spec.bootOptions = vim.vm.BootOptions(
bootOrder=[vim.vm.BootOptions.BootableCdromDevice()]
)
vm_spec.deviceChange = device_specs
# Create VM
task = conn.datacenter.vmFolder.CreateVM_Task(
config=vm_spec, pool=conn.resource_pool
task = self.conn.datacenter.vmFolder.CreateVM_Task(
config=vm_spec, pool=self.conn.resource_pool
)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' created successfully"
@ -284,33 +216,31 @@ class VMLifecycleMixin(VSphereMixin):
new_name: str,
power_on: bool = False,
datastore: str | None = None,
host: str | None = None,
) -> str:
"""Clone a VM from a template or existing VM."""
conn = self._conn(host)
template_vm = conn.find_vm(template_name)
template_vm = self.conn.find_vm(template_name)
if not template_vm:
raise ValueError(f"Template VM '{template_name}' not found")
vm_folder = template_vm.parent
if not isinstance(vm_folder, vim.Folder):
vm_folder = conn.datacenter.vmFolder
vm_folder = self.conn.datacenter.vmFolder
# Resolve datastore
datastore_obj = conn.datastore
datastore_obj = self.conn.datastore
if datastore:
datastore_obj = conn.find_datastore(datastore)
datastore_obj = self.conn.find_datastore(datastore)
if not datastore_obj:
raise ValueError(f"Datastore '{datastore}' not found")
resource_pool = template_vm.resourcePool or conn.resource_pool
resource_pool = template_vm.resourcePool or self.conn.resource_pool
relocate_spec = vim.vm.RelocateSpec(pool=resource_pool, datastore=datastore_obj)
clone_spec = vim.vm.CloneSpec(
powerOn=power_on, template=False, location=relocate_spec
)
task = template_vm.Clone(folder=vm_folder, name=new_name, spec=clone_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{new_name}' cloned from '{template_name}'"
@ -319,20 +249,19 @@ class VMLifecycleMixin(VSphereMixin):
description="Delete a virtual machine permanently (powers off if running)",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def delete_vm(self, name: str, host: str | None = None) -> str:
def delete_vm(self, name: str) -> str:
"""Delete a virtual machine permanently."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
# Power off if running
if vm.runtime.powerState == vim.VirtualMachine.PowerState.poweredOn:
task = vm.PowerOffVM_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
task = vm.Destroy_Task()
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' deleted"
@ -347,11 +276,9 @@ class VMLifecycleMixin(VSphereMixin):
cpu: int | None = None,
memory_mb: int | None = None,
annotation: str | None = None,
host: str | None = None,
) -> str:
"""Reconfigure VM hardware settings."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
@ -374,7 +301,7 @@ class VMLifecycleMixin(VSphereMixin):
return f"No changes specified for VM '{name}'"
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM '{name}' reconfigured: {', '.join(changes)}"
@ -383,82 +310,13 @@ class VMLifecycleMixin(VSphereMixin):
description="Rename a virtual machine",
annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True),
)
def rename_vm(self, name: str, new_name: str, host: str | None = None) -> str:
def rename_vm(self, name: str, new_name: str) -> str:
"""Rename a virtual machine."""
conn = self._conn(host)
vm = conn.find_vm(name)
vm = self.conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
task = vm.Rename_Task(newName=new_name)
conn.wait_for_task(task)
self.conn.wait_for_task(task)
return f"VM renamed from '{name}' to '{new_name}'"
@mcp_tool(
name="set_boot_order",
description="Set a VM's BIOS boot device order (e.g. ['cdrom','disk'])",
annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True),
)
def set_boot_order(
self, name: str, order: list[str], host: str | None = None
) -> dict[str, Any]:
"""Set the VM's boot device order.
Args:
name: VM name
order: Boot devices in priority order. Each entry is one of:
'cdrom' (CD/DVD), 'disk' (hard disk), 'ethernet'/'network' (PXE),
or 'floppy'. Devices not listed are tried after those listed.
host: Managed ESXi host to target (default: the default host)
Returns:
Dict with the applied boot order
"""
conn = self._conn(host)
vm = conn.find_vm(name)
if not vm:
raise ValueError(f"VM '{name}' not found")
disk_key = next(
(d.key for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualDisk)),
None,
)
nic_key = next(
(d.key for d in vm.config.hardware.device
if isinstance(d, vim.vm.device.VirtualEthernetCard)),
None,
)
boot_devices = []
for item in order:
kind = item.strip().lower()
if kind in ("cdrom", "cd", "dvd"):
boot_devices.append(vim.vm.BootOptions.BootableCdromDevice())
elif kind in ("disk", "hdd", "hd"):
if disk_key is None:
raise ValueError("VM has no virtual disk to boot from")
boot_devices.append(
vim.vm.BootOptions.BootableDiskDevice(deviceKey=disk_key)
)
elif kind in ("ethernet", "nic", "network", "pxe"):
if nic_key is None:
raise ValueError("VM has no network adapter to boot from")
boot_devices.append(
vim.vm.BootOptions.BootableEthernetDevice(deviceKey=nic_key)
)
elif kind in ("floppy", "fd"):
boot_devices.append(vim.vm.BootOptions.BootableFloppyDevice())
else:
raise ValueError(
f"Unknown boot device '{item}'. Use cdrom/disk/ethernet/floppy."
)
config_spec = vim.vm.ConfigSpec(
bootOptions=vim.vm.BootOptions(bootOrder=boot_devices)
)
task = vm.ReconfigVM_Task(spec=config_spec)
conn.wait_for_task(task)
return {"vm": name, "boot_order": [d.strip().lower() for d in order]}

11
src/mcvsphere/permissions.py
View File

@ -120,11 +120,10 @@ TOOL_PERMISSIONS: dict[str, PermissionLevel] = {
"configure_ntp": PermissionLevel.HOST_ADMIN,
"set_service_policy": PermissionLevel.HOST_ADMIN,
# ═══════════════════════════════════════════════════════════════════════
# FULL_ADMIN - Everything including guest OS and service control (11 tools)
# FULL_ADMIN - Everything including guest OS and service control (10 tools)
# ═══════════════════════════════════════════════════════════════════════
"start_service": PermissionLevel.FULL_ADMIN,
"stop_service": PermissionLevel.FULL_ADMIN,
"restart_service": PermissionLevel.FULL_ADMIN,
# Guest OS operations (requires guest credentials, high privilege)
"run_command_in_guest": PermissionLevel.FULL_ADMIN,
"list_guest_processes": PermissionLevel.FULL_ADMIN,
@ -192,10 +191,9 @@ def get_user_permissions(groups: list[str] | None) -> set[PermissionLevel]:
Returns:
Set of granted permission levels (union of all group permissions).
Returns empty set if no recognized groups (deny all access).
"""
if not groups:
return set() # No groups = no permissions (enforces RBAC)
return {PermissionLevel.READ_ONLY}
permissions: set[PermissionLevel] = set()
@ -203,7 +201,10 @@ def get_user_permissions(groups: list[str] | None) -> set[PermissionLevel]:
if group in GROUP_PERMISSIONS:
permissions.update(GROUP_PERMISSIONS[group])
# No fallback - unrecognized groups get no permissions
# Default to read-only if no recognized groups
if not permissions:
permissions.add(PermissionLevel.READ_ONLY)
return permissions

62
src/mcvsphere/server.py
View File

@ -8,8 +8,7 @@ from fastmcp import FastMCP
from mcvsphere.auth import create_auth_provider
from mcvsphere.config import Settings, get_settings
from mcvsphere.connection_manager import ConnectionManager
from mcvsphere.middleware import RBACMiddleware
from mcvsphere.connection import VMwareConnection
from mcvsphere.mixins import (
ConsoleMixin,
DiskManagementMixin,
@ -25,7 +24,6 @@ from mcvsphere.mixins import (
VCenterOpsMixin,
VMLifecycleMixin,
)
from mcvsphere.servers import ServerConfig, load_servers
logger = logging.getLogger(__name__)
@ -70,48 +68,25 @@ def create_server(settings: Settings | None = None) -> FastMCP:
auth=auth,
)
# Add RBAC middleware when OAuth is enabled
if settings.oauth_enabled:
mcp.add_middleware(RBACMiddleware())
logger.info("RBAC middleware enabled - permissions enforced via OAuth groups")
# Build the managed-server inventory (pluggable source: ESXI_HOST[_N] env
# now, an API later). Fall back to the single VCENTER_* server if no
# ESXI_* hosts are configured.
servers = load_servers()
if not servers:
servers = [
ServerConfig(
host=settings.vcenter_host,
user=settings.vcenter_user,
password=settings.vcenter_password,
insecure=settings.vcenter_insecure,
network=settings.vcenter_network,
)
]
manager = ConnectionManager(servers, settings)
logger.info(
"Managing %d ESXi host(s); connecting to default %s...",
len(manager.hosts),
manager.default_host,
)
manager.get() # eager-connect the default host (fail fast); others are lazy
# Create shared VMware connection
logger.info("Connecting to VMware vCenter/ESXi...")
conn = VMwareConnection(settings)
# Create and register all mixins
mixins = [
VMLifecycleMixin(manager),
PowerOpsMixin(manager),
SnapshotsMixin(manager),
MonitoringMixin(manager),
GuestOpsMixin(manager),
ResourcesMixin(manager),
DiskManagementMixin(manager),
NICManagementMixin(manager),
OVFManagementMixin(manager),
HostManagementMixin(manager),
VCenterOpsMixin(manager),
ConsoleMixin(manager),
SerialPortMixin(manager),
VMLifecycleMixin(conn),
PowerOpsMixin(conn),
SnapshotsMixin(conn),
MonitoringMixin(conn),
GuestOpsMixin(conn),
ResourcesMixin(conn),
DiskManagementMixin(conn),
NICManagementMixin(conn),
OVFManagementMixin(conn),
HostManagementMixin(conn),
VCenterOpsMixin(conn),
ConsoleMixin(conn),
SerialPortMixin(conn),
]
tool_count = 0
@ -162,9 +137,8 @@ def run_server(config_path: Path | None = None) -> None:
)
if settings.oauth_enabled:
print(f"OAuth: ENABLED via {settings.oauth_issuer_url}", file=sys.stderr)
print("RBAC: ENABLED - permissions enforced via groups", file=sys.stderr)
else:
print("OAuth: disabled (single-user mode)", file=sys.stderr)
print("OAuth: disabled", file=sys.stderr)
print("─" * 40, file=sys.stderr)
# Create and run server

112
src/mcvsphere/servers.py
View File

@ -1,112 +0,0 @@
"""ESXi server inventory — the pluggable source of hosts to manage.
This module is the single seam between "where the server list comes from" and
the rest of the app. Today ``load_servers`` reads ``ESXI_HOST[_N]`` environment
variables (from ``.env`` or the process environment). When mcvsphere becomes an
HTTP service, replace ``load_servers`` with an API-backed implementation —
nothing downstream depends on the source, only on the ``ServerConfig`` shape.
"""
import os
from typing import TYPE_CHECKING
from dotenv import dotenv_values
from pydantic import BaseModel, SecretStr
if TYPE_CHECKING:
from mcvsphere.config import Settings
class ServerConfig(BaseModel):
"""A single ESXi host to manage. Servers are identified by ``host``."""
host: str
user: str
password: SecretStr
insecure: bool = True
network: str = "VM Network"
def to_settings(self, base: "Settings") -> "Settings":
"""Derive a per-server Settings from the base settings.
Connection fields are overridden with this server's values; everything
else (transport, OAuth, logging) is inherited so a single VMwareConnection
can be built per host without duplicating global config.
"""
return base.model_copy(
update={
"vcenter_host": self.host,
"vcenter_user": self.user,
"vcenter_password": self.password,
"vcenter_insecure": self.insecure,
"vcenter_network": self.network,
}
)
def _as_bool(value: str | None, default: bool = True) -> bool:
if value is None or value == "":
return default
return str(value).lower() in ("true", "1", "yes", "on")
def load_servers(env_file: str = ".env") -> list[ServerConfig]:
"""Return the list of ESXi servers to manage.
Source seam — currently the ``ESXI_HOST[_N]`` env-var families:
ESXI_HOST / ESXI_USER / ESXI_PASS [/ ESXI_INSECURE / ESXI_NETWORK]
ESXI_HOST_1 / ESXI_USER_1 / ESXI_PASS_1 [/ ...]
ESXI_HOST_2 / ...
Rules:
- Servers are keyed by ``host``; the first (unsuffixed ``ESXI_HOST``) is the
default used when a tool call omits ``host``.
- A suffixed host that omits its own USER/PASS/INSECURE/NETWORK inherits the
unsuffixed ``ESXI_USER``/``ESXI_PASS``/``ESXI_INSECURE``/``ESXI_NETWORK``.
- ``.env`` and the real environment are merged (environment wins), so the
list works whether vars are exported or only present in ``.env``.
"""
env: dict[str, str | None] = {**dotenv_values(env_file), **os.environ}
base_user = env.get("ESXI_USER")
base_pass = env.get("ESXI_PASS")
base_insecure = env.get("ESXI_INSECURE")
base_network = env.get("ESXI_NETWORK")
# Discover suffixes in order: "" (base), then _1, _2, ... while present.
suffixes: list[str] = []
if env.get("ESXI_HOST"):
suffixes.append("")
index = 1
while env.get(f"ESXI_HOST_{index}"):
suffixes.append(f"_{index}")
index += 1
servers: list[ServerConfig] = []
seen: set[str] = set()
for suffix in suffixes:
host = env.get(f"ESXI_HOST{suffix}")
if not host or host in seen:
continue
user = env.get(f"ESXI_USER{suffix}") or base_user
password = env.get(f"ESXI_PASS{suffix}") or base_pass
if not user or not password:
# Incomplete credentials and no base fallback — skip this host.
continue
insecure = env.get(f"ESXI_INSECURE{suffix}")
if insecure is None:
insecure = base_insecure
network = env.get(f"ESXI_NETWORK{suffix}") or base_network or "VM Network"
seen.add(host)
servers.append(
ServerConfig(
host=host,
user=user,
password=SecretStr(password),
insecure=_as_bool(insecure),
network=network,
)
)
return servers