list_taxes

Instructions

Implementation Reference

• src/aviationstack_mcp/server.py:1072-1089 (registration)

  MCP tool registration for 'list_taxes' using @mcp.tool decorator. Defines the tool wrapper that validates input via ListTaxesInput and delegates to the core list_taxes function.

  @mcp.tool(
      name="list_taxes",
      description="List aviation taxes with pagination and optional search.",
  )
  def list_taxes_tool(
      limit: Annotated[
          int, Field(description="Maximum number of tax records to return.", gt=0)
      ] = 10,
      offset: Annotated[int, Field(description="Offset for pagination.", ge=0)] = 0,
      search: Annotated[str, Field(description="Optional tax search text.")] = "",
  ) -> str:
      """Tool wrapper for list_taxes."""
      validated_input = ListTaxesInput(limit=limit, offset=offset, search=search)
      return list_taxes(
          limit=validated_input.limit,
          offset=validated_input.offset,
          search=validated_input.search,
      )

• src/aviationstack_mcp/server.py:777-798 (handler)

  Core handler for list_taxes. Validates limit/offset, builds params, calls _list_reference_data with 'taxes' endpoint and maps each tax to tax_id, tax_name, iata_code. Handles request and value errors.

  def list_taxes(limit: int = 10, offset: int = 0, search: str = "") -> str:
      """List aviation taxes (available on all plans)."""
      try:
          _validate_positive_int(limit, "limit")
          _validate_non_negative_int(offset, "offset")
          params: dict[str, Any] = {"limit": limit, "offset": offset}
          if search:
              params["search"] = search
  
          return _list_reference_data(
              "taxes",
              params,
              lambda tax: {
                  "tax_id": tax.get("tax_id"),
                  "tax_name": tax.get("tax_name"),
                  "iata_code": tax.get("iata_code"),
              },
          )
      except requests.RequestException as exc:
          return _error_response("fetching taxes", exc)
      except (KeyError, ValueError, TypeError) as exc:
          return _error_response("fetching taxes", exc)

• src/aviationstack_mcp/server.py:280-298 (schema)

  Pydantic input schema ListTaxesInput with fields: limit (gt=0, default=10), offset (ge=0, default=0), search (default=''). Extra fields forbidden.

  class ListTaxesInput(BaseModel):
      """Input schema for list_taxes tool."""
  
      model_config = ConfigDict(extra="forbid")
  
      limit: int = Field(
          default=10,
          description="Maximum number of tax records to return.",
          gt=0,
      )
      offset: int = Field(
          default=0,
          description="Offset for pagination.",
          ge=0,
      )
      search: str = Field(
          default="",
          description="Optional tax search text.",
      )

• src/aviationstack_mcp/server.py:376-382 (helper)

  Generic helper _list_reference_data used by list_taxes. Fetches data from Aviationstack API endpoint, applies a mapper function, and returns JSON string of the results.

  def _list_reference_data(
      endpoint: str,
      params: dict[str, Any],
      mapper: Callable[[dict[str, Any]], dict[str, Any]],
  ) -> str:
      data = fetch_flight_data(endpoint, params)
      return json.dumps([mapper(item) for item in data.get("data", [])])

• src/aviationstack_mcp/server.py:331-332 (helper)

  Error response helper _error_response used by list_taxes to return a JSON error on request/value errors.

  def _error_response(context: str, exc: Exception) -> str:
      return json.dumps({"ok": False, "context": context, "error": str(exc)})