aliases

Instructions

Implementation Reference

• opnsense_mcp/tools/aliases.py:38-65 (handler)

  The execute() method of AliasesTool — core handler logic for the 'aliases' tool. Calls client.search_aliases() and returns results with count and status.

  async def execute(self, params: dict[str, Any] | None = None) -> dict[str, Any]:
      """
      List firewall aliases with optional filtering.
  
      Args:
          params: Optional dict with 'search' key.
  
      Returns:
          Dictionary containing aliases and count.
  
      """
      if params is None:
          params = {}
  
      if not self.client:
          return {"status": "error", "error": "No client available"}
  
      try:
          search = params.get("search", "")
          aliases = await self.client.search_aliases(search)
          return {
              "aliases": aliases,
              "count": len(aliases),
              "status": "success",
          }
      except Exception as e:
          logger.exception("Failed to list firewall aliases")
          return {"status": "error", "error": str(e)}

• opnsense_mcp/tools/aliases.py:16-26 (schema)

  Input schema for the 'aliases' tool: optional 'search' string parameter.

  input_schema = {
      "type": "object",
      "properties": {
          "search": {
              "type": "string",
              "description": "Filter by alias name, type, or content",
              "optional": True,
          },
      },
      "required": [],
  }

• opnsense_mcp/server.py:739-742 (registration)

  Tool registration in the tools list endpoint response: name 'aliases' with description and inputSchema.

  {
      "name": "aliases",
      "description": "List firewall aliases (IP groups, port groups, etc)",
      "inputSchema": {

• opnsense_mcp/server.py:936-942 (registration)

  Dispatch logic: routes 'aliases' tool calls to AliasesTool.execute().

  if tool_name == "aliases":
      result = await aliases_tool.execute(arguments)
      return {
          "jsonrpc": "2.0",
          "id": msg_id,
          "result": {"content": [{"type": "text", "text": str(result)}]},
      }

• opnsense_mcp/server.py:1007-1008 (registration)

  Instantiation of AliasesTool with client for later use.

  aliases_tool = AliasesTool(client)
  gateway_status_tool = GatewayStatusTool(client)

• opnsense_mcp/utils/api.py:1145-1156 (helper)

  API helper search_aliases() makes POST to /api/firewall/alias/searchItem and returns rows.

  async def search_aliases(self, search: str = "") -> list[dict[str, Any]]:
      """List firewall aliases, optionally filtered."""
      try:
          data = await self._make_request(
              "POST",
              ENDPOINTS["alias"]["search"],
              json={"current": 1, "rowCount": 100, "searchPhrase": search},
          )
          return data.get("rows", []) if isinstance(data, dict) else []
      except Exception:
          logger.exception("Failed to search aliases")
          return []

• opnsense_mcp/utils/mock_api.py:204-217 (helper)

  Mock implementation of search_aliases() for testing.

  async def search_aliases(self, search: str = "") -> list[dict[str, Any]]:
      """Return mock firewall aliases."""
      data = self.mock_data.get("aliases", {})
      rows = data.get("rows", []) if isinstance(data, dict) else []
      if not search:
          return rows
      search_lc = search.lower()
      return [
          row
          for row in rows
          if search_lc in str(row.get("name", "")).lower()
          or search_lc in str(row.get("description", "")).lower()
          or search_lc in str(row.get("content", "")).lower()
      ]

• opnsense_mcp/utils/api.py:67-69 (helper)

  ENDPOINTS definition: alias search endpoint at /api/firewall/alias/searchItem.

  "alias": {
      "search": "/api/firewall/alias/searchItem",
  },