OPNSense MCP Server

Instructions

Implementation Reference

• src/plugins/core/core-firewall/index.ts:415-444 (handler)

  Handler function for the firewall_toggle_rule tool. Calls OPNsense API to toggle the rule status, applies changes, emits event, updates cache, and returns success status.

  private async toggleRule(params: { uuid: string }): Promise<any> {
    try {
      const response = await this.api.post(`/api/firewall/filter/toggleRule/${params.uuid}`);
  
      if (response.data?.result === 'saved') {
        // Apply changes
        await this.applyChanges({});
  
        // Emit event
        this.emit('firewall.rule.toggled', {
          uuid: params.uuid,
          enabled: response.data.enabled,
        });
  
        // Invalidate cache
        this.ruleCache.delete(params.uuid);
  
        return {
          success: true,
          enabled: response.data.enabled === '1',
          message: 'Firewall rule toggled successfully',
        };
      }
  
      throw new Error('Failed to toggle firewall rule');
    } catch (error) {
      this.logger.error(`Error toggling firewall rule ${params.uuid}:`, error);
      throw error;
    }
  }

• src/plugins/core/core-firewall/index.ts:168-181 (registration)

  Registers the 'firewall_toggle_rule' MCP tool in the plugin's getTools() method, specifying name, description, input schema (requires uuid), and binds to toggleRule handler.

    name: 'firewall_toggle_rule',
    description: 'Toggle a firewall rule enabled/disabled',
    inputSchema: {
      type: 'object',
      properties: {
        uuid: {
          type: 'string',
          description: 'Rule UUID',
        },
      },
      required: ['uuid'],
    },
    handler: this.toggleRule.bind(this),
  },

• src/plugins/core/core-firewall/index.ts:170-179 (schema)

  Input schema for firewall_toggle_rule tool requiring a single 'uuid' string property.

  inputSchema: {
    type: 'object',
    properties: {
      uuid: {
        type: 'string',
        description: 'Rule UUID',
      },
    },
    required: ['uuid'],
  },

• src/resources/firewall/rule.ts:404-412 (helper)

  Supporting toggle method in FirewallRuleResource class that retrieves rule, flips enabled state, and updates it. Used in scripts but not directly in MCP plugin handler.

  async toggle(uuid: string): Promise<boolean> {
    const rule = await this.get(uuid);
    if (!rule) {
      throw new Error(`Firewall rule ${uuid} not found`);
    }
  
    const newState = rule.enabled === '1' ? '0' : '1';
    return this.update(uuid, { enabled: newState });
  }