custom-emission-calculation

Instructions

Implementation Reference

• src/climatiq_mcp_server/tools.py:391-448 (handler)

  The primary handler function that implements the logic for the 'custom-emission-calculation' tool. It takes an activity_id, value, and unit, constructs a request to the Climatiq API, processes the response, and returns formatted results with caching.

  async def custom_emission_calculation_tool(config, arguments, server, climatiq_request):
      """
      Calculate emissions using a specific emission factor by activity ID.
      
      This advanced tool allows for precise carbon calculations using any emission factor 
      available in the Climatiq database. Users need to specify:
      - The exact activity_id (which can be found using the search-emission-factors tool)
      - The value of the activity (e.g., amount consumed, distance traveled)
      - The unit of measurement (e.g., kWh, km, kg)
      
      This tool is highly flexible and can be used for any emission calculation supported
      by Climatiq when you know the specific emission factor you need to use.
      """
      activity_id = arguments.get("activity_id")
      value = arguments.get("value")
      unit = arguments.get("unit")
      
      if not activity_id or value is None or not unit:
          raise ValueError("Missing required parameters for custom emission calculation")
          
      # Construct the request to the Climatiq API
      request_data = {
          "emission_factor": {
              "activity_id": activity_id,
              "data_version": config["data_version"]
          },
          "parameters": {
              unit: value
          }
      }
      
      try:
          result = await climatiq_request("/data/v1/estimate", request_data)
          
          # Store in cache
          cache_id = f"custom_{activity_id}_{value}_{unit}_{id(result)}"
          
          co2e = result.get("co2e", 0)
          co2e_unit = result.get("co2e_unit", "kg")
          factor_name = result.get("emission_factor", {}).get("name", "Custom factor")
          
          result_text = f"Custom calculation using '{factor_name}' activity:\n"
          result_text += f"{value} {unit} results in {co2e} {co2e_unit} of CO2e emissions."
          
          if "emission_factor" in result:
              ef = result["emission_factor"]
              result_text += f"\n\nFactor details:"
              result_text += f"\nName: {ef.get('name', 'N/A')}"
              result_text += f"\nRegion: {ef.get('region', 'Global')}"
              result_text += f"\nSource: {ef.get('source', 'Unknown')}"
          
          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 in custom emission calculation: {str(e)}"
          raise ValueError(error_msg)

• src/climatiq_mcp_server/tools.py:807-819 (registration)

  The tool registration definition in get_tool_definitions(), including the name, description, and input schema for the MCP server to recognize and validate calls to this tool.

  types.Tool(
      name="custom-emission-calculation",
      description="Calculate emissions using any specific emission factor identified by its activity_id, allowing for precise and flexible carbon calculations.",
      inputSchema={
          "type": "object",
          "properties": {
              "activity_id": {"type": "string", "description": "Emission factor activity ID (found via search-emission-factors)"},
              "value": {"type": "number", "description": "Activity value (amount of the activity)"},
              "unit": {"type": "string", "description": "Activity unit (e.g., kWh, km, kg, etc.)"},
          },
          "required": ["activity_id", "value", "unit"],
      },
  ),

• src/climatiq_mcp_server/server.py:254-255 (handler)

  The dispatch logic in the main @server.call_tool() handler that routes calls to 'custom-emission-calculation' to the specific tool function.

  elif name == "custom-emission-calculation":
      result_text, result, cache_id = await custom_emission_calculation_tool(config, arguments, server, climatiq_request)

• src/climatiq_mcp_server/tools.py:810-818 (schema)

  The input schema definition specifying the required parameters and their types for the custom-emission-calculation tool.

  inputSchema={
      "type": "object",
      "properties": {
          "activity_id": {"type": "string", "description": "Emission factor activity ID (found via search-emission-factors)"},
          "value": {"type": "number", "description": "Activity value (amount of the activity)"},
          "unit": {"type": "string", "description": "Activity unit (e.g., kWh, km, kg, etc.)"},
      },
      "required": ["activity_id", "value", "unit"],
  },