electricity-emission

Instructions

Implementation Reference

• src/climatiq_mcp_server/tools.py:56-106 (handler)

  Handler function that performs the electricity emission calculation by querying the Climatiq API with the appropriate emission factor and parameters.

  async def electricity_emission_tool(config, arguments, server, climatiq_request):
      """
      Calculate carbon emissions from electricity consumption.
      
      This tool calculates the greenhouse gas emissions associated with electricity usage based on:
      - The amount of energy consumed (in kWh, MWh, etc.)
      - The region/country where the electricity is consumed (affecting the grid mix)
      
      It uses Climatiq's electricity emission factors which account for the specific energy 
      generation mix of the specified region, providing accurate CO2e estimations.
      """
      energy = arguments.get("energy")
      energy_unit = arguments.get("energy_unit")
      region = arguments.get("region", "US")
      
      if not energy or not energy_unit:
          raise ValueError("Missing required parameters for electricity emission calculation")
          
      # Construct the request to the Climatiq API
      request_data = {
          "emission_factor": {
              "activity_id": "electricity-supply_grid-source_residual_mix",
              "data_version": config["data_version"],
              "region": region
          },
          "parameters": {
              "energy": energy,
              "energy_unit": energy_unit
          }
      }
      
      try:
          result = await climatiq_request("/data/v1/estimate", request_data)
          
          # Store in cache
          cache_id = f"electricity_{energy}_{energy_unit}_{region}_{id(result)}"
          
          co2e = result.get("co2e", 0)
          co2e_unit = result.get("co2e_unit", "kg")
          result_text = f"Electricity consumption of {energy} {energy_unit} in {region} results in {co2e} {co2e_unit} of CO2e emissions."
          
          if "emission_factor" in result and result["emission_factor"].get("name"):
              ef_name = result["emission_factor"]["name"]
              result_text += f"\nEmission factor used: {ef_name}"
          
          result_text += f"\n\nDetailed results are available as a resource with ID: {cache_id}"
          
          return result_text, result, cache_id
      except Exception as e:
          error_msg = f"Error calculating electricity emissions: {str(e)}"
          raise ValueError(error_msg)

• src/climatiq_mcp_server/tools.py:759-767 (schema)

  Input schema defining the parameters for the electricity-emission tool: energy (number), energy_unit (string), region (string, default 'US').

  inputSchema={
      "type": "object",
      "properties": {
          "energy": {"type": "number", "description": "Amount of energy consumed"},
          "energy_unit": {"type": "string", "description": "Energy unit (kWh, MWh, etc.)"},
          "region": {"type": "string", "description": "Region code (e.g., US, GB, FR) representing the electricity grid location", "default": "US"},
      },
      "required": ["energy", "energy_unit"],
  },

• src/climatiq_mcp_server/server.py:248-249 (registration)

  Dispatch logic in the MCP call_tool handler that routes 'electricity-emission' tool calls to the electricity_emission_tool function.

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

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

  MCP server.list_tools() handler that returns the list of tool definitions, including electricity-emission, via get_tool_definitions().

  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/tools.py:756-768 (registration)

  Tool registration definition in get_tool_definitions() that defines the electricity-emission tool name, description, and schema for MCP server.

  types.Tool(
      name="electricity-emission",
      description="Calculate carbon emissions from electricity consumption based on energy amount and regional grid mix.",
      inputSchema={
          "type": "object",
          "properties": {
              "energy": {"type": "number", "description": "Amount of energy consumed"},
              "energy_unit": {"type": "string", "description": "Energy unit (kWh, MWh, etc.)"},
              "region": {"type": "string", "description": "Region code (e.g., US, GB, FR) representing the electricity grid location", "default": "US"},
          },
          "required": ["energy", "energy_unit"],
      },
  ),