opnsense_route_gateway_update

Instructions

Implementation Reference

• src/tools/routing.ts:51-61 (schema)

  Zod schema validating inputs for opnsense_route_gateway_update: uuid (required), monitor_disable, monitor, disabled, defaultgw, description, weight (1-30), priority (1-255), confirm (must be true).

  const GatewayUpdateSchema = z.object({
    uuid: UuidSchema,
    monitor_disable: CoerceBoolean.optional(),
    monitor: z.string().optional(),
    disabled: CoerceBoolean.optional(),
    defaultgw: CoerceBoolean.optional(),
    description: z.string().optional(),
    weight: z.coerce.number().int().min(1).max(30).optional(),
    priority: z.coerce.number().int().min(1).max(255).optional(),
    confirm: ConfirmTrue("confirm must be true to proceed with the gateway update"),
  });

• src/tools/routing.ts:256-310 (handler)

  Handler logic for opnsense_route_gateway_update: parses args via GatewayUpdateSchema, round-trips current gateway config via GET /routing/settings/getGateway/{uuid}, overrides only explicitly provided fields, builds flat object with bool-to-flag conversion, then POSTs to /routing/settings/setGateway/{uuid}.

  case "opnsense_route_gateway_update": {
    const parsed = GatewayUpdateSchema.parse(args);
  
    // Round-trip: get current state, flatten multi-selects, override only provided fields
    const current = (await client.get<{ gateway_item?: Record<string, unknown> }>(
      `/routing/settings/getGateway/${encodeURIComponent(parsed.uuid)}`,
    ))?.gateway_item ?? {};
  
    const flat: Record<string, unknown> = {
      name: extractSelected(current["name"]) ?? current["name"],
      descr: parsed.description ?? (extractSelected(current["descr"]) ?? current["descr"] ?? ""),
      interface: extractSelected(current["interface"]) ?? "",
      ipprotocol: extractSelected(current["ipprotocol"]) ?? "inet",
      gateway: extractSelected(current["gateway"]) ?? current["gateway"] ?? "",
      defaultgw:
        boolToFlag(parsed.defaultgw) ??
        (extractSelected(current["defaultgw"]) ?? current["defaultgw"] ?? "0"),
      fargw: extractSelected(current["fargw"]) ?? current["fargw"] ?? "",
      monitor_disable:
        boolToFlag(parsed.monitor_disable) ??
        (extractSelected(current["monitor_disable"]) ?? current["monitor_disable"] ?? "0"),
      monitor_noroute:
        extractSelected(current["monitor_noroute"]) ?? current["monitor_noroute"] ?? "",
      monitor:
        parsed.monitor !== undefined
          ? parsed.monitor
          : (extractSelected(current["monitor"]) ?? current["monitor"] ?? ""),
      force_down: extractSelected(current["force_down"]) ?? current["force_down"] ?? "",
      priority:
        parsed.priority !== undefined
          ? String(parsed.priority)
          : (extractSelected(current["priority"]) ?? current["priority"] ?? "255"),
      weight:
        parsed.weight !== undefined
          ? String(parsed.weight)
          : (extractSelected(current["weight"]) ?? current["weight"] ?? "1"),
      latencylow: extractSelected(current["latencylow"]) ?? current["latencylow"] ?? "",
      latencyhigh: extractSelected(current["latencyhigh"]) ?? current["latencyhigh"] ?? "",
      losslow: extractSelected(current["losslow"]) ?? current["losslow"] ?? "",
      losshigh: extractSelected(current["losshigh"]) ?? current["losshigh"] ?? "",
      interval: extractSelected(current["interval"]) ?? current["interval"] ?? "",
      time_period: extractSelected(current["time_period"]) ?? current["time_period"] ?? "",
      loss_interval: extractSelected(current["loss_interval"]) ?? current["loss_interval"] ?? "",
      data_length: extractSelected(current["data_length"]) ?? current["data_length"] ?? "",
      disabled:
        boolToFlag(parsed.disabled) ??
        (extractSelected(current["disabled"]) ?? current["disabled"] ?? "0"),
    };
  
    const result = await client.post(
      `/routing/settings/setGateway/${encodeURIComponent(parsed.uuid)}`,
      { gateway_item: flat },
    );
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/tools/routing.ts:152-169 (registration)

  Tool definition entry in routingToolDefinitions array: registers name 'opnsense_route_gateway_update', description, and inputSchema (matching GatewayUpdateSchema) for ListTools capability.

  {
    name: "opnsense_route_gateway_update",
    description: "Update an existing gateway's settings (toggle monitoring, set monitor IP, change weight/priority, enable/disable). Round-trips current config and only overrides explicitly provided fields. After updating, call opnsense_route_gateway_apply to activate the change. DESTRUCTIVE: requires explicit confirmation.",
    inputSchema: {
      type: "object" as const,
      properties: {
        uuid: { type: "string", description: "Gateway UUID (from opnsense_route_gateway_list)" },
        monitor_disable: { type: "boolean", description: "Disable gateway monitoring (true = no health probe)" },
        monitor: { type: "string", description: "Monitor IP address (used when monitor_disable=false). Empty string clears it." },
        disabled: { type: "boolean", description: "Disable the gateway entirely" },
        defaultgw: { type: "boolean", description: "Mark as default gateway" },
        description: { type: "string", description: "Human-readable description" },
        weight: { type: "number", description: "Load-balancing weight (1-30)" },
        priority: { type: "number", description: "Failover priority (1-255, lower = higher priority)" },
        confirm: { type: "boolean", description: "Must be true to confirm the update", enum: [true] },
      },
      required: ["uuid", "confirm"],
    },

• src/index.ts:67-67 (registration)

  Registration: routes all routingToolDefinitions (including opnsense_route_gateway_update) to handleRoutingTool in the MCP server's tool handler map.

  for (const def of routingToolDefinitions) toolHandlers.set(def.name, handleRoutingTool);

• src/tools/routing.ts:69-72 (helper)

  boolToFlag helper: converts JavaScript boolean to OPNsense '0'/'1' string representation, used for monitor_disable, defaultgw, and disabled fields.

  function boolToFlag(v: boolean | undefined): string | undefined {
    if (v === undefined) return undefined;
    return v ? "1" : "0";
  }