VPS_createFirewallRuleV1

Instructions

Implementation Reference

• src/core/tools/vps.ts:573-635 (schema)

  Tool schema definition for VPS_createFirewallRuleV1 - defines name, description, HTTP method (POST), path (/api/vps/v1/firewall/{firewallId}/rules), and input schema with required fields (firewallId, protocol, port, source, source_detail). Note: the ruleId param from the OpenAPI spec was dropped from the required list (unlike the update endpoint which includes it).

  {
    "name": "VPS_createFirewallRuleV1",
    "description": "Create new firewall rule for a specified firewall.\n\nBy default, the firewall drops all incoming traffic,\nwhich means you must add accept rules for all ports you want to use.\n\nAny virtual machine that has this firewall activated will lose sync with the firewall\nand will have to be synced again manually.\n\nUse this endpoint to add new security rules to firewalls.",
    "method": "POST",
    "path": "/api/vps/v1/firewall/{firewallId}/rules",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firewallId": {
          "type": "integer",
          "description": "Firewall ID"
        },
        "protocol": {
          "type": "string",
          "description": "protocol parameter",
          "enum": [
            "TCP",
            "UDP",
            "ICMP",
            "GRE",
            "any",
            "ESP",
            "AH",
            "ICMPv6",
            "SSH",
            "HTTP",
            "HTTPS",
            "MySQL",
            "PostgreSQL"
          ]
        },
        "port": {
          "type": "string",
          "description": "Port or port range, ex: 1024:2048"
        },
        "source": {
          "type": "string",
          "description": "source parameter",
          "enum": [
            "any",
            "custom"
          ]
        },
        "source_detail": {
          "type": "string",
          "description": "IP range, CIDR, single IP or `any`"
        }
      },
      "required": [
        "firewallId",
        "protocol",
        "port",
        "source",
        "source_detail"
      ]
    },
    "security": [
      {
        "apiToken": []
      }
    ],
    "group": "vps"
  },

• src/core/tools/vps.ts:573-635 (handler)

  Handler: This tool has no custom handler. It is executed via the generic executeApiCall() method in runtime.ts which constructs an HTTP request based on the tool's method and path, substituting path parameters from input params.

  {
    "name": "VPS_createFirewallRuleV1",
    "description": "Create new firewall rule for a specified firewall.\n\nBy default, the firewall drops all incoming traffic,\nwhich means you must add accept rules for all ports you want to use.\n\nAny virtual machine that has this firewall activated will lose sync with the firewall\nand will have to be synced again manually.\n\nUse this endpoint to add new security rules to firewalls.",
    "method": "POST",
    "path": "/api/vps/v1/firewall/{firewallId}/rules",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firewallId": {
          "type": "integer",
          "description": "Firewall ID"
        },
        "protocol": {
          "type": "string",
          "description": "protocol parameter",
          "enum": [
            "TCP",
            "UDP",
            "ICMP",
            "GRE",
            "any",
            "ESP",
            "AH",
            "ICMPv6",
            "SSH",
            "HTTP",
            "HTTPS",
            "MySQL",
            "PostgreSQL"
          ]
        },
        "port": {
          "type": "string",
          "description": "Port or port range, ex: 1024:2048"
        },
        "source": {
          "type": "string",
          "description": "source parameter",
          "enum": [
            "any",
            "custom"
          ]
        },
        "source_detail": {
          "type": "string",
          "description": "IP range, CIDR, single IP or `any`"
        }
      },
      "required": [
        "firewallId",
        "protocol",
        "port",
        "source",
        "source_detail"
      ]
    },
    "security": [
      {
        "apiToken": []
      }
    ],
    "group": "vps"
  },

• src/servers/vps.ts:3-5 (registration)

  Registration entry point - the VPS tools array (including VPS_createFirewallRuleV1) is imported from src/core/tools/vps.js and passed into the startServer function which registers all tools with the MCP SDK.

  import { startServer } from '../core/runtime.js';
  import tools from '../core/tools/vps.js';

• src/core/runtime.ts:86-99 (registration)

  Registration: The MCPServer.initializeTools() method iterates over the tool list and registers each tool (including VPS_createFirewallRuleV1) by name in the internal tools Map for MCP SDK.

    // Set up request handlers - don't log here
    this.setupHandlers();
  }
  
  /**
   * Parse headers from string
   */
  private parseHeaders(headerStr: string): Record<string, string> {
    const headers: Record<string, string> = {};
    if (headerStr) {
      headerStr.split(",").forEach((header) => {
        const [key, value] = header.split(":");
        if (key && value) headers[key.trim()] = value.trim();
      });

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

  Generic API handler - VPS_createFirewallRuleV1 is not a custom tool so it uses executeApiCall(), which builds an HTTP request from the tool's method (POST) and path (/api/vps/v1/firewall/{firewallId}/rules), substituting path params from input and sending remaining params as JSON body.

    this.log('info', `Resolving username from domain: ${domain}`);
    const username = await this.resolveUsername(domain);
  
    const queryParams = this.hosting_showJsDeploymentLogs_buildQueryParams(params);
  
    let logs: any;
    try {
      this.log('info', `Fetching logs for ${domain}, build ${buildUuid}`);
      logs = await this.hosting_showJsDeploymentLogs_fetchLogs(username, domain, buildUuid, queryParams);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      this.log('error', `Failed to fetch logs: ${errorMessage}`);
      throw error;
    }
  
    const effectiveFromLine = (typeof fromLine === 'number' && Number.isInteger(fromLine) && fromLine >= 0) ? fromLine : 0;
  
    return {
      domain,
      username,
      buildUuid,
      fromLine: effectiveFromLine,
      logs
    };
  }
  
  /**
   * Execute an API call for a tool
   */
  private async executeApiCall(tool: OpenApiTool, params: Record<string, any>): Promise<any> {
    // 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: AxiosRequestConfig = {
        method: method.toLowerCase(),
        url,
        headers: { ...this.headers },
        timeout: 60000, // 60s
        validateStatus: function (status: number): boolean {
          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) {
        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;
        if (config.headers) {
          config.headers["Content-Type"] = "application/json";
        }
      }
  
      this.log('debug', "Request config:", {
        url: config.url,
        method: config.method,