VPS_getProjectContainersV1

Instructions

Implementation Reference

• src/core/tools/vps.ts:30-57 (schema)

  Input schema and tool definition for VPS_getProjectContainersV1. Defines it as a GET request to /api/vps/v1/virtual-machines/{virtualMachineId}/docker/{projectName}/containers with required parameters: virtualMachineId (integer) and projectName (string).

  {
    "name": "VPS_getProjectContainersV1",
    "description": "Retrieves a list of all containers belonging to a specific Docker Compose project on the virtual machine. \n\nThis endpoint returns detailed information about each container including\ntheir current status, port mappings, and runtime configuration.\n\nUse this to monitor the health and state of all services within your Docker Compose project.",
    "method": "GET",
    "path": "/api/vps/v1/virtual-machines/{virtualMachineId}/docker/{projectName}/containers",
    "inputSchema": {
      "type": "object",
      "properties": {
        "virtualMachineId": {
          "type": "integer",
          "description": "Virtual Machine ID"
        },
        "projectName": {
          "type": "string",
          "description": "Docker Compose project name using alphanumeric characters, dashes, and underscores only"
        }
      },
      "required": [
        "virtualMachineId",
        "projectName"
      ]
    },
    "security": [
      {
        "apiToken": []
      }
    ],
    "group": "vps"

• src/core/tools/vps.js:20-48 (schema)

  Input schema and tool definition (JS version) for VPS_getProjectContainersV1. Identical definition to the TS file.

  {
    "name": "VPS_getProjectContainersV1",
    "description": "Retrieves a list of all containers belonging to a specific Docker Compose project on the virtual machine. \n\nThis endpoint returns detailed information about each container including\ntheir current status, port mappings, and runtime configuration.\n\nUse this to monitor the health and state of all services within your Docker Compose project.",
    "method": "GET",
    "path": "/api/vps/v1/virtual-machines/{virtualMachineId}/docker/{projectName}/containers",
    "inputSchema": {
      "type": "object",
      "properties": {
        "virtualMachineId": {
          "type": "integer",
          "description": "Virtual Machine ID"
        },
        "projectName": {
          "type": "string",
          "description": "Docker Compose project name using alphanumeric characters, dashes, and underscores only"
        }
      },
      "required": [
        "virtualMachineId",
        "projectName"
      ]
    },
    "security": [
      {
        "apiToken": []
      }
    ],
    "group": "vps"
  },

• src/servers/vps.js:3-6 (registration)

  Entry point that registers all VPS tools (including VPS_getProjectContainersV1) with the MCP server by importing the tool list and passing it to startServer.

  import { startServer } from '../core/runtime.js';
  import tools from '../core/tools/vps.js';
  
  startServer({ name: 'hostinger-vps-mcp', version: '0.1.41', tools });

• src/core/runtime.js:1879-1966 (handler)

  Generic API call executor used for VPS_getProjectContainersV1. Since this tool is not 'custom', it uses executeApiCall which substitutes path parameters ({virtualMachineId}, {projectName}) from input params and makes a GET request to the Hostinger API.

  async executeApiCall(tool, params) {
    // Get method and path from tool
    const method = tool.method;
    let path = tool.path;
  
    // Clone params to avoid modifying the original
    const requestParams = { ...params };
  
    // Replace path parameters with values from params
    Object.entries(requestParams).forEach(([key, value]) => {
      const placeholder = `{${key}}`;
      if (path.includes(placeholder)) {
        path = path.replace(placeholder, encodeURIComponent(String(value)));
        delete requestParams[key]; // Remove used parameter
      }
    });
  
    // Build the full URL
    const baseUrl = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
    const cleanPath = path.startsWith("/") ? path.slice(1) : path;
    const url = new URL(cleanPath, baseUrl).toString();
  
    this.log('debug', `API Request: ${method} ${url}`);
  
    try {
      // Configure the request
      const config = {
        method: method.toLowerCase(),
        url,
        headers: { ...this.headers },
        timeout: 60000, // 60s
        validateStatus: function (status) {
          return status < 500; // Resolve only if the status code is less than 500
        }
      };
    
      const bearerToken = process.env['API_TOKEN'] || process.env['APITOKEN']; // APITOKEN for backwards compatibility
      if (bearerToken) {
        config.headers['Authorization'] = `Bearer ${bearerToken}`;
      } else {
        this.log('error', `Bearer Token environment variable not found: API_TOKEN`);
      }
  
      // Add parameters based on request method
      if (["GET", "DELETE"].includes(method)) {
        // For GET/DELETE, send params as query string
        config.params = { ...(config.params || {}), ...requestParams };
      } else {
        // For POST/PUT/PATCH, send params as JSON body
        config.data = requestParams;
        config.headers["Content-Type"] = "application/json";
      }
  
      this.log('debug', "Request config:", {
        url: config.url,
        method: config.method,
        params: config.params,
        headers: Object.keys(config.headers)
      });
  
      // Execute the request
      const response = await axios(config);
      this.log('debug', `Response status: ${response.status}`);
  
      return response.data;
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      this.log('error', `API request failed: ${errorMessage}`);
  
      if (axios.isAxiosError(error)) {
        const responseData = error.response?.data;
        const responseStatus = error.response?.status;
  
        this.log('error', 'API Error Details:', {
          status: responseStatus,
          data: typeof responseData === 'object' ? JSON.stringify(responseData) : responseData
        });
  
        // Rethrow with more context for better error handling
        const detailedError = new Error(`API request failed with status ${responseStatus}: ${errorMessage}`);
        detailedError.response = error.response;
        throw detailedError;
      }
  
      throw error;
    }
  }