freight-emission

Instructions

Implementation Reference

• src/climatiq_mcp_server/tools.py:507-576 (handler)

  The handler function that executes the freight-emission tool: parses arguments, maps mode to Climatiq activity_id, calls the API, processes and caches the result.

  async def freight_emission_tool(config, arguments, server, climatiq_request):
      """
      Calculate carbon emissions from freight transportation.
      
      This tool estimates greenhouse gas emissions from moving goods via different freight modes:
      - Truck/road freight
      - Rail freight
      - Sea/shipping freight
      - Air freight
      
      The calculation considers:
      - The weight of goods being transported
      - The distance traveled
      - The specific transport mode
      
      It's especially useful for logistics companies, supply chain operations, and 
      organizations looking to understand and reduce their shipping-related carbon footprint.
      """
      mode = arguments.get("mode")
      weight = arguments.get("weight")
      weight_unit = arguments.get("weight_unit", "t")
      distance = arguments.get("distance")
      distance_unit = arguments.get("distance_unit", "km")
      
      if not mode or not weight or not distance:
          raise ValueError("Missing required parameters for freight emission calculation")
          
      # Different activity IDs based on freight mode
      activity_id = ""
      
      if mode.lower() == "truck" or mode.lower() == "road":
          activity_id = "freight_vehicle-vehicle_type_truck-fuel_source_na-vehicle_weight_na-vehicle_age_na"
      elif mode.lower() == "rail":
          activity_id = "freight_train-route_type_na-fuel_source_na"
      elif mode.lower() in ["ship", "sea", "marine"]:
          activity_id = "sea_freight-vessel_type_na-route_type_na-fuel_source_na"
      elif mode.lower() in ["air", "plane", "aircraft"]:
          activity_id = "air_freight-route_type_na-distance_na"
      else:
          raise ValueError(f"Unsupported freight mode: {mode}")
          
      # Construct the request to the Climatiq API
      request_data = {
          "emission_factor": {
              "activity_id": activity_id,
              "data_version": config["data_version"]
          },
          "parameters": {
              "weight": weight,
              "weight_unit": weight_unit,
              "distance": distance,
              "distance_unit": distance_unit
          }
      }
      
      result = await climatiq_request("/data/v1/estimate", request_data)
      
      # Store in cache
      cache_id = f"freight_{mode}_{weight}_{weight_unit}_{distance}_{distance_unit}_{id(result)}"
      
      co2e = result.get("co2e", 0)
      co2e_unit = result.get("co2e_unit", "kg")
      
      mode_display = mode.capitalize()
      result_text = f"{mode_display} freight of {weight} {weight_unit} over {distance} {distance_unit} "
      result_text += f"results in {co2e} {co2e_unit} of CO2e emissions."
      result_text += f"\n\nDetailed results are available as a resource with ID: {cache_id}"
      
      return result_text, result, cache_id

• src/climatiq_mcp_server/tools.py:835-849 (schema)

  Defines the tool schema including name, description, and inputSchema with properties for mode, weight, distance, units.

  types.Tool(
      name="freight-emission",
      description="Calculate emissions from freight transportation across different modes (truck, rail, ship, air) based on weight and distance.",
      inputSchema={
          "type": "object",
          "properties": {
              "mode": {"type": "string", "description": "Freight mode (truck, rail, ship, air)"},
              "weight": {"type": "number", "description": "Weight of goods transported"},
              "weight_unit": {"type": "string", "description": "Weight unit (t, kg)", "default": "t"},
              "distance": {"type": "number", "description": "Distance transported"},
              "distance_unit": {"type": "string", "description": "Distance unit (km, mi)", "default": "km"},
          },
          "required": ["mode", "weight", "distance"],
      },
  ),

• src/climatiq_mcp_server/server.py:258-259 (registration)

  Tool dispatch in handle_call_tool: routes 'freight-emission' calls to the freight_emission_tool handler.

  elif name == "freight-emission":
      result_text, result, cache_id = await freight_emission_tool(config, arguments, server, climatiq_request)

• src/climatiq_mcp_server/server.py:224-229 (registration)

  Registers all MCP tools (including freight-emission) via server.list_tools() by returning get_tool_definitions().

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """
      List available tools for interacting with the Climatiq API.
      """
      return get_tool_definitions()

• src/climatiq_mcp_server/server.py:32-43 (registration)

  Imports the freight_emission_tool handler and get_tool_definitions from tools.py for use in server.

  from climatiq_mcp_server.tools import (
      set_api_key_tool,
      electricity_emission_tool,
      travel_emission_tool,
      search_emission_factors_tool,
      custom_emission_calculation_tool,
      cloud_computing_emission_tool,
      freight_emission_tool,
      procurement_emission_tool,
      hotel_emission_tool,
      travel_spend_tool,
      get_tool_definitions