vme-mcp-server 0.1.7 → 0.1.9

package/dist/README.md

@@ -1,6 +1,6 @@
 # VME MCP Server
 
-Transform VMware infrastructure management into conversational AI interactions with Claude.
+Transform HPE VM Essentials infrastructure management into conversational AI interactions with Claude.
 
 ## Installation
 
@@ -15,8 +15,8 @@ npm install -g vme-mcp-server
 Create a `.env` file:
 
 ```bash
-# VMware Configuration
-VME_API_BASE_URL=https://your-vme-instance.com/api
+# HPE VM Essentials Configuration
+VME_API_BASE_URL=https://your-hpe-vme-instance.com/api
 VME_API_TOKEN=your-bearer-token
 
 # Privacy Controls (Optional)
@@ -72,7 +72,7 @@ Restart Claude Desktop. You should see the VME MCP Server tools available.
 ## Features
 
 ### Intelligent Resource Discovery
-- Unified API consolidating multiple VMware endpoints
+- Unified API consolidating multiple HPE VM Essentials endpoints
 - Intent-aware responses based on context
 - Semantic organization of compute vs infrastructure resources
 
@@ -90,11 +90,44 @@ Restart Claude Desktop. You should see the VME MCP Server tools available.
 
 ## Configuration
 
+### Environment Variable Loading (Global Install Support)
+
+The server automatically searches for `.env` files in multiple locations:
+
+1. **Current directory**: `./env` (for local development)
+2. **Home directory**: `~/.env` (for global installs)
+3. **Config directory**: `~/.config/vme-mcp-server/.env`
+4. **Documents folder**: `~/Documents/.env.vme-mcp-server`
+
+### Recommended Configuration Methods
+
+**Method 1: Direct Environment Variables (Best for Global Install)**
+
+Add to your Claude Desktop config (`~/.config/claude-desktop/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "vme-mcp-server": {
+      "command": "vme-mcp-server",
+      "env": {
+        "VME_API_BASE_URL": "https://your-hpe-vme-instance.com/api",
+        "VME_API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+**Method 2: .env File (Good for Local Development)**
+
+Create `.env` file in any of the supported locations above.
+
 ### Required Environment Variables
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `VME_API_BASE_URL` | VMware vCenter API endpoint | `https://vcenter.company.com/api` |
+| `VME_API_BASE_URL` | HPE VM Essentials API endpoint | `https://vme.company.com/api` |
 | `VME_API_TOKEN` | Bearer token for authentication | `your-bearer-token` |
 
 ### Optional Environment Variables
@@ -117,10 +150,10 @@ Restart Claude Desktop. You should see the VME MCP Server tools available.
 **"API connection failed"**
 - Verify `VME_API_BASE_URL` is correct and accessible
 - Check that `VME_API_TOKEN` has sufficient permissions
-- Ensure network connectivity to VMware infrastructure
+- Ensure network connectivity to HPE VM Essentials infrastructure
 
 **"VM creation failed"**
-- Verify user permissions in VMware for VM creation
+- Verify user permissions in HPE VM Essentials for VM creation
 - Check that specified service plans and templates exist
 - Ensure target group/zone has available resources
 
@@ -128,7 +161,7 @@ Restart Claude Desktop. You should see the VME MCP Server tools available.
 
 - Check the `.env.example` file for configuration templates
 - Review error messages for specific guidance
-- Ensure VMware infrastructure is accessible and properly configured
+- Ensure HPE VM Essentials infrastructure is accessible and properly configured
 
 ## Architecture
 
@@ -143,6 +176,6 @@ Built with TypeScript and the Model Context Protocol for seamless Claude integra
 
 ## Version
 
-Current version: 0.1.5
+Current version: 0.1.9
 
 For development documentation and contribution guidelines, see the project repository.

package/dist/lib/api-utils.js

@@ -13,19 +13,32 @@ exports.api = axios_1.default.create({
         "Content-Type": "application/json"
     }
 });
-// Helper function to get available cluster nodes
+// Helper function to get available cluster nodes (hypervisor hosts, not VMs)
 async function getClusterNodes() {
     try {
+        // Get actual cluster hypervisor nodes from /clusters endpoint
         const clusters = await exports.api.get("/clusters");
-        const prodCluster = clusters.data.clusters.find((cluster) => cluster.name === "prod01");
-        if (prodCluster && prodCluster.servers) {
-            return prodCluster.servers.map((server) => server.id);
+        let allNodes = [];
+        if (clusters.data.clusters) {
+            for (const cluster of clusters.data.clusters) {
+                if (cluster.servers && Array.isArray(cluster.servers)) {
+                    const clusterNodes = cluster.servers.map((server) => server.id).filter((id) => id);
+                    allNodes.push(...clusterNodes);
+                }
+            }
+        }
+        // Remove duplicates and sort
+        const uniqueNodes = [...new Set(allNodes)].sort((a, b) => a - b);
+        if (uniqueNodes.length > 0) {
+            console.log(`Found ${uniqueNodes.length} cluster hypervisor nodes: ${uniqueNodes.join(', ')}`);
+            return uniqueNodes;
         }
     }
     catch (error) {
         console.error('Error getting cluster nodes:', error);
     }
-    // Fallback to known nodes if API fails
+    // Fallback to known hypervisor nodes if API fails
+    console.warn('Using fallback hypervisor nodes [1, 2, 3] - could not detect cluster hosts');
     return [1, 2, 3];
 }
 exports.getClusterNodes = getClusterNodes;

package/dist/lib/vm-parsing.js

@@ -3,10 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateNodeAssignments = exports.parseVMNames = void 0;
 // Helper function to parse VM name patterns
 function parseVMNames(nameInput, count) {
-    // Handle range patterns like "web01->web03" or "web01 -> web03"
-    const rangeMatch = nameInput.match(/^(.+?)(\d+)\s*->\s*(.+?)(\d+)$/);
-    if (rangeMatch) {
-        const [, prefix1, start, prefix2, end] = rangeMatch;
+    // Handle letter range patterns like "ws-a->ws-x" or "ws-a -> ws-x"
+    const letterRangeMatch = nameInput.match(/^(.+?)([a-z])\s*->\s*(.+?)([a-z])$/i);
+    if (letterRangeMatch) {
+        const [, prefix1, startLetter, prefix2, endLetter] = letterRangeMatch;
+        if (prefix1.trim() === prefix2.trim()) {
+            const basePrefix = prefix1.trim();
+            const startCode = startLetter.toLowerCase().charCodeAt(0);
+            const endCode = endLetter.toLowerCase().charCodeAt(0);
+            const names = [];
+            for (let i = startCode; i <= endCode; i++) {
+                const letter = String.fromCharCode(i);
+                names.push(`${basePrefix}${letter}`);
+            }
+            return names;
+        }
+    }
+    // Handle numeric range patterns like "web01->web03" or "web01 -> web03"
+    const numericRangeMatch = nameInput.match(/^(.+?)(\d+)\s*->\s*(.+?)(\d+)$/);
+    if (numericRangeMatch) {
+        const [, prefix1, start, prefix2, end] = numericRangeMatch;
         if (prefix1.trim() === prefix2.trim()) {
             const basePrefix = prefix1.trim();
             const startNum = parseInt(start);
@@ -57,21 +73,13 @@ function calculateNodeAssignments(vmNames, nodes, distribution) {
             nodeAssignments.push({ name: vmName, kvmHostId: nodeId });
         });
     }
-    else if (distribution && distribution !== 'auto') {
-        // Parse specific node assignments like "1,2,3" or "node1,node2,node3"
-        const specifiedNodes = distribution.split(',').map((n) => {
-            const trimmed = n.trim();
-            return trimmed.startsWith('node') ? parseInt(trimmed.replace('node', '')) : parseInt(trimmed);
-        }).filter((n) => !isNaN(n));
-        if (specifiedNodes.length > 0) {
-            vmNames.forEach((vmName, index) => {
-                const nodeId = specifiedNodes[index % specifiedNodes.length];
-                nodeAssignments.push({ name: vmName, kvmHostId: nodeId });
-            });
-        }
-        else {
-            nodeAssignments = vmNames.map(vmName => ({ name: vmName }));
-        }
+    else if (distribution && !['auto', 'spread'].includes(distribution)) {
+        // Distribution is a node/hypervisor name - signal that it needs resolution
+        // Return assignments with the node name for the calling function to resolve
+        nodeAssignments = vmNames.map(vmName => ({
+            name: vmName,
+            nodeNameToResolve: distribution
+        }));
     }
     else {
         // Auto-placement (no kvmHostId specified)

package/dist/server.js

@@ -9,15 +9,41 @@ const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const dotenv_1 = __importDefault(require("dotenv"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
 const index_js_2 = require("./tools/index.js");
-// Load environment variables
-dotenv_1.default.config();
+// Load environment variables from multiple locations for global install support
+function loadEnvironmentConfig() {
+    // Priority order for .env file locations:
+    const envPaths = [
+        // 1. Current working directory (for local development)
+        (0, path_1.join)(process.cwd(), '.env'),
+        // 2. Home directory (for global installs)
+        (0, path_1.join)((0, os_1.homedir)(), '.env'),
+        // 3. XDG config directory (Linux/Mac standard)
+        (0, path_1.join)((0, os_1.homedir)(), '.config', 'vme-mcp-server', '.env'),
+        // 4. User's Documents folder (Windows-friendly)
+        (0, path_1.join)((0, os_1.homedir)(), 'Documents', '.env.vme-mcp-server')
+    ];
+    // Try to load .env from the first available location
+    for (const envPath of envPaths) {
+        if ((0, fs_1.existsSync)(envPath)) {
+            dotenv_1.default.config({ path: envPath });
+            console.error(`VME MCP: Loaded config from ${envPath}`);
+            return;
+        }
+    }
+    // If no .env file found, that's okay - environment variables may be set directly
+    console.error('VME MCP: No .env file found, using direct environment variables');
+}
+loadEnvironmentConfig();
 // Disable TLS verification for VME API (if needed)
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 // Create VME MCP server with modular architecture
 const server = new index_js_1.Server({
     name: "vme-mcp-server",
-    version: "1.5.0",
+    version: "0.1.9",
 }, {
     capabilities: {
         tools: {},

package/dist/tools/create-vm.js

@@ -6,7 +6,7 @@ const api_utils_js_1 = require("../lib/api-utils.js");
 const name_resolver_js_1 = require("../lib/name-resolver.js");
 exports.createVMTool = {
     name: "create_vm",
-    description: "Provision a new virtual machine",
+    description: "Provision a new virtual machine. ⚡ TIP: Run discover_capabilities first to see available groups, zones, templates, and sizes in your environment.",
     inputSchema: {
         type: "object",
         properties: {
@@ -71,6 +71,30 @@ async function handleCreateVM(args) {
     const nodes = await (0, api_utils_js_1.getClusterNodes)();
     // Calculate node assignments
     const nodeAssignments = (0, vm_parsing_js_1.calculateNodeAssignments)(vmNames, nodes, distribution);
+    // Resolve any node names to IDs
+    for (const assignment of nodeAssignments) {
+        if (assignment.nodeNameToResolve) {
+            // Query servers to find node with matching name
+            try {
+                const servers = await api_utils_js_1.api.get("/servers");
+                if (servers.data.servers) {
+                    const foundServer = servers.data.servers.find((server) => server.name?.toLowerCase() === assignment.nodeNameToResolve?.toLowerCase());
+                    if (foundServer) {
+                        assignment.kvmHostId = foundServer.id;
+                        delete assignment.nodeNameToResolve; // Clean up
+                    }
+                    else {
+                        // If no exact name match, log available servers for debugging
+                        const availableNames = servers.data.servers.map((s) => s.name).filter(Boolean);
+                        console.warn(`Node '${assignment.nodeNameToResolve}' not found. Available: ${availableNames.join(', ')}`);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`Failed to resolve node name '${assignment.nodeNameToResolve}':`, error);
+            }
+        }
+    }
     // Use name resolver to get IDs from actual VME environment
     const groupId = await name_resolver_js_1.nameResolver.resolveNameToId('group', group);
     const cloudId = await name_resolver_js_1.nameResolver.resolveNameToId('zone', location);

package/dist/tools/discover-capabilities.js

@@ -4,7 +4,7 @@ exports.handleDiscoverCapabilities = exports.discoverCapabilitiesTool = void 0;
 const capability_discovery_js_1 = require("../lib/capability-discovery.js");
 exports.discoverCapabilitiesTool = {
     name: "discover_capabilities",
-    description: "Discover VME infrastructure capabilities with intelligent filtering and caching",
+    description: "⚡ RECOMMENDED FIRST STEP: Discover VME infrastructure capabilities to learn available resources. Run this tool at least once per session to cache environment data for optimal performance with other tools.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/get-resources.js

@@ -4,7 +4,7 @@ exports.handleGetResources = exports.getResourcesTool = void 0;
 const api_utils_js_1 = require("../lib/api-utils.js");
 exports.getResourcesTool = {
     name: "get_resources",
-    description: "Discover and explore available VME infrastructure resources with intelligent filtering",
+    description: "Discover and explore available VME infrastructure resources with intelligent filtering. ⚡ TIP: Use discover_capabilities for comprehensive environment discovery first.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/query-resources.js

@@ -4,18 +4,24 @@ exports.handleQueryResources = exports.queryResourcesTool = void 0;
 const api_utils_js_1 = require("../lib/api-utils.js");
 exports.queryResourcesTool = {
     name: "query_resources",
-    description: "Query actual infrastructure resources (VMs, hosts, networks) with natural language. Use discover_capabilities first to learn available OS types, groups, and statuses in your environment.",
+    description: "Query actual infrastructure resources (VMs, cluster nodes, networks) with natural language. Supports network placement queries. ⚡ TIP: Run discover_capabilities first to learn available OS types, groups, and statuses in your environment.",
     inputSchema: {
         type: "object",
         properties: {
             natural_query: {
                 type: "string",
-                description: "Natural language query like 'Windows VMs', 'stopped VMs in production', 'any VMs?', 'Ubuntu hosts', 'VMs in development group'"
+                description: "Natural language query like 'Windows VMs', 'stopped VMs in production', 'DNS servers', 'VMs named ns01', 'VMs on management network', 'any VMs?'"
             },
             limit: {
                 type: "number",
                 description: "Maximum number of results to return (default: 10, max: 100)",
                 default: 10
+            },
+            detail_level: {
+                type: "number",
+                description: "Information detail level: 1=basic (name, status, IP), 2=standard (+ network, plan), 3=full (all available fields)",
+                enum: [1, 2, 3],
+                default: 2
             }
         },
         required: ["natural_query"]
@@ -25,9 +31,19 @@ function parseResourceQuery(query, limit = 10) {
     const q = query.toLowerCase().trim();
     // Determine resource type
     let resource = 'instances'; // default
-    if (q.includes('host') || q.includes('server') || q.includes('node')) {
+    if (q.includes('cluster') && (q.includes('node') || q.includes('host'))) {
+        resource = 'cluster_nodes';
+    }
+    else if (q.includes('hypervisor') || q.includes('vme01') || q.includes('vme02') || q.includes('vme03')) {
+        resource = 'cluster_nodes';
+    }
+    else if (q.includes('host') || q.includes('server')) {
         resource = 'hosts';
     }
+    else if (q.includes('node') && !q.includes('cluster')) {
+        // When someone just says "nodes" without "cluster", assume they want cluster nodes
+        resource = 'cluster_nodes';
+    }
     else if (q.includes('network')) {
         resource = 'networks';
     }
@@ -77,6 +93,19 @@ function parseResourceQuery(query, limit = 10) {
     if (nameMatch) {
         filters.name = nameMatch[1];
     }
+    // Network patterns
+    if (q.includes('network') || q.includes('vlan')) {
+        const networkMatch = q.match(/on\s+["']?([a-zA-Z0-9\-_\s]+)["']?/);
+        if (networkMatch) {
+            filters.network = networkMatch[1].trim();
+        }
+        else if (q.includes('management')) {
+            filters.network = 'management';
+        }
+        else if (q.includes('compute')) {
+            filters.network = 'compute';
+        }
+    }
     return { resource, action, filters, limit };
 }
 function filterResults(data, filters) {
@@ -110,10 +139,103 @@ function filterResults(data, filters) {
             if (!itemName.includes(filters.name.toLowerCase()))
                 return false;
         }
+        // Network filtering
+        if (filters.network) {
+            const networkName = item.interfaces?.[0]?.network?.name?.toLowerCase() || '';
+            const networkPool = item.interfaces?.[0]?.network?.pool?.name?.toLowerCase() || '';
+            const filterNetwork = filters.network.toLowerCase();
+            if (!networkName.includes(filterNetwork) && !networkPool.includes(filterNetwork)) {
+                return false;
+            }
+        }
         return true;
     });
 }
-function formatResponse(parsedQuery, results, totalCount) {
+function mapItemByDetailLevel(item, resource, detailLevel) {
+    // Level 1: Basic information only
+    const basicInfo = {
+        id: item.id,
+        name: item.name,
+        status: item.status
+    };
+    if (detailLevel === 1) {
+        return {
+            ...basicInfo,
+            ...(resource === 'instances' && {
+                ipAddress: item.connectionInfo?.[0]?.ip || item.externalIp || item.internalIp
+            })
+        };
+    }
+    // Level 2: Standard information (default)
+    const standardInfo = {
+        ...basicInfo,
+        osType: item.osType,
+        group: item.group?.name || item.site?.name || 'unknown',
+        ...(resource === 'instances' && {
+            plan: item.plan?.name,
+            powerState: item.powerState,
+            ipAddress: item.connectionInfo?.[0]?.ip || item.externalIp || item.internalIp,
+            networkName: item.interfaces?.[0]?.network?.name,
+            networkPool: item.interfaces?.[0]?.network?.pool?.name
+        })
+    };
+    if (detailLevel === 2) {
+        return standardInfo;
+    }
+    // Level 3: Full information 
+    return {
+        ...standardInfo,
+        ...(resource === 'instances' && {
+            networkId: item.interfaces?.[0]?.network?.id,
+            interfaceCount: item.interfaces?.length || 0,
+            allInterfaces: item.interfaces?.map((iface) => ({
+                id: iface.id,
+                networkName: iface.network?.name,
+                ipAddress: iface.ipAddress,
+                ipMode: iface.ipMode
+            })) || [],
+            firewallEnabled: item.firewallEnabled,
+            networkLevel: item.networkLevel,
+            externalId: item.externalId,
+            hostname: item.hostname,
+            displayName: item.displayName,
+            maxMemory: item.maxMemory,
+            maxCores: item.maxCores,
+            dateCreated: item.dateCreated,
+            lastUpdated: item.lastUpdated
+        }),
+        ...(resource === 'hosts' && {
+            serverType: item.serverType?.name,
+            zone: item.zone?.name,
+            powerState: item.powerState,
+            agentInstalled: item.agentInstalled,
+            maxMemory: item.maxMemory,
+            maxCores: item.maxCores,
+            freeMemory: item.freeMemory,
+            usedMemory: item.usedMemory
+        }),
+        ...(resource === 'networks' && {
+            type: item.type?.name,
+            zone: item.zone?.name,
+            pool: item.pool?.name,
+            dhcpServer: item.dhcpServer,
+            dnsPrimary: item.dnsPrimary,
+            dnsSecondary: item.dnsSecondary,
+            gateway: item.gateway,
+            netmask: item.netmask,
+            cidr: item.cidr
+        }),
+        ...(resource === 'cluster_nodes' && {
+            hostname: item.hostname,
+            serverType: item.serverType?.name || item.serverType,
+            powerState: item.powerState,
+            cpuCount: item.maxCpu,
+            memoryGB: item.maxMemory ? Math.floor(item.maxMemory / (1024 * 1024 * 1024)) : undefined,
+            vmCount: item.instances?.length || 0
+        })
+    };
+}
+function formatResponse(parsedQuery, results, totalCount, detailLevel = 2) {
     const { action, resource, filters } = parsedQuery;
     if (action === 'count') {
         return {
@@ -153,24 +275,14 @@ function formatResponse(parsedQuery, results, totalCount) {
         filters_applied: filters,
         total_count: results.length,
         returned_count: limitedResults.length,
-        items: limitedResults.map(item => ({
-            id: item.id,
-            name: item.name,
-            status: item.status,
-            osType: item.osType,
-            group: item.group?.name || item.site?.name || 'unknown',
-            ...(resource === 'instances' && {
-                plan: item.plan?.name,
-                powerState: item.powerState,
-                ipAddress: item.externalIp || item.internalIp
-            })
-        })),
+        detail_level: detailLevel,
+        items: limitedResults.map(item => mapItemByDetailLevel(item, resource, detailLevel)),
         query_summary: `Showing ${limitedResults.length} of ${results.length} ${resource} matching criteria`
     };
 }
 async function handleQueryResources(args) {
     try {
-        const { natural_query, limit = 10 } = args;
+        const { natural_query, limit = 10, detail_level = 2 } = args;
         if (!natural_query || typeof natural_query !== 'string') {
             return {
                 content: [
@@ -191,7 +303,8 @@ async function handleQueryResources(args) {
         const endpointMap = {
             'instances': '/instances',
             'hosts': '/servers',
-            'networks': '/networks'
+            'networks': '/networks',
+            'cluster_nodes': '/clusters'
         };
         const endpoint = endpointMap[parsedQuery.resource];
         // Query the VME API
@@ -207,6 +320,16 @@ async function handleQueryResources(args) {
         else if (parsedQuery.resource === 'networks' && response.data.networks) {
             rawData = response.data.networks;
         }
+        else if (parsedQuery.resource === 'cluster_nodes' && response.data.clusters) {
+            // Extract hypervisor nodes from clusters
+            const allNodes = [];
+            for (const cluster of response.data.clusters) {
+                if (cluster.servers && Array.isArray(cluster.servers)) {
+                    allNodes.push(...cluster.servers);
+                }
+            }
+            rawData = allNodes;
+        }
         else {
             // Fallback: try to find array in response
             const possibleArrays = Object.values(response.data).filter(Array.isArray);
@@ -217,7 +340,7 @@ async function handleQueryResources(args) {
         // Apply filters
         const filteredResults = filterResults(rawData, parsedQuery.filters);
         // Format response based on action
-        const formattedResponse = formatResponse(parsedQuery, filteredResults, rawData.length);
+        const formattedResponse = formatResponse(parsedQuery, filteredResults, rawData.length, detail_level);
         return {
             content: [
                 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vme-mcp-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "",
   "main": "dist/server.js",
   "bin": {