get_portco_emissions

Instructions

Implementation Reference

• server.py:101-135 (handler)

  The `get_portco_emissions` function is a FastMCP tool that retrieves Scope 1 and Scope 2 emissions for a specific portfolio company. It accepts `portco` (slug or name), optional `year`, and optional `scope` (1 or 2) parameters. It resolves the portco slug via `_resolve_portco`, computes yearly emissions via `_year_totals` (summing quarterly data), optionally filters by scope, and returns a dict with portco metadata, base year/target totals, and the emissions map in tCO2e.

  @mcp.tool()
  def get_portco_emissions(
      portco: str, year: int | None = None, scope: int | None = None
  ) -> dict[str, Any]:
      """
      Get Scope 1 and Scope 2 emissions for a specific portfolio company.
  
      Args:
          portco: Portco slug (e.g. 'meridian') or name substring (e.g. 'Meridian').
          year:   Optional. Restrict to a single year (e.g. 2024). If omitted,
                  returns totals for every available year.
          scope:  Optional. 1 or 2 to filter to a single scope. If omitted, returns both.
  
      Returns:
          Dict with portco metadata and an 'emissions' map of {year: {scope1, scope2, total}}
          in tCO2e. Values are tonnes CO2-equivalent.
      """
      slug = _resolve_portco(portco)
      p = PORTCOS[slug]
      totals = _year_totals(slug, year)
  
      if scope in (1, 2):
          key = f"scope{scope}"
          totals = {y: {key: v[key]} for y, v in totals.items()}
  
      return {
          "portco": p["name"],
          "slug": slug,
          "sector": p["sector"],
          "base_year": p["baseYear"],
          "base_year_total_tco2e": TRAJECTORY[slug]["baseYearTotal"],
          "target_2030_tco2e": TRAJECTORY[slug]["target2030"],
          "emissions": totals,
          "units": "tCO2e",
      }

• server.py:72-72 (registration)

  The `@mcp.tool()` decorator on line 72 (and implicitly for all tool functions) registers `get_portco_emissions` with the FastMCP server under the name 'northwood-carbon'.

  @mcp.tool()

• server.py:55-68 (helper)

  The `_year_totals` helper function sums quarterly emissions from the TRAJECTORY data for a given portco slug. It aggregates scope1, scope2, and total per year, and optionally filters to a specific year. This is used by `get_portco_emissions` to compute per-year emissions.

  def _year_totals(slug: str, year: int | None = None) -> dict[str, float]:
      """Sum quarterly emissions for a portco. If year is None, returns all years."""
      traj = TRAJECTORY[slug]["quarters"]
      result: dict[str, dict[str, float]] = {}
      for q in traj:
          y = int(q["q"].split("-")[1])
          if year is not None and y != year:
              continue
          key = str(y)
          result.setdefault(key, {"scope1": 0.0, "scope2": 0.0, "total": 0.0})
          result[key]["scope1"] += q["scope1"]
          result[key]["scope2"] += q["scope2"]
          result[key]["total"] += q["scope1"] + q["scope2"]
      return result

• server.py:42-52 (helper)

  The `_resolve_portco` helper resolves a portco identifier (slug or name substring, case-insensitive) to its canonical slug key in the PORTCOS dictionary. Raises ValueError if no match found.

  def _resolve_portco(portco: str) -> str:
      """Match portco by slug or name (case-insensitive). Raises on miss."""
      key = portco.strip().lower()
      if key in PORTCOS:
          return key
      for slug, p in PORTCOS.items():
          if p["name"].lower().startswith(key) or key in p["name"].lower():
              return slug
      raise ValueError(
          f"Unknown portco '{portco}'. Known slugs: {', '.join(PORTCOS.keys())}"
      )

• server.py:9-9 (registration)

  Comment listing `get_portco_emissions` as one of the available tools in the module docstring.

  - get_portco_emissions     — scope 1/2 emissions for a portco, optionally by year