carbon_footprint_calculator

Instructions

Implementation Reference

• src/tools/carbon-footprint-calculator.ts:217-219 (handler)

  The handler function that executes the carbon footprint calculator tool logic. It delegates to callGapupEndpoint with the slug 'carbon-footprint-calculator'.

  export async function handle(input: unknown, signal?: AbortSignal): Promise<unknown> {
    return callGapupEndpoint("carbon-footprint-calculator", input, signal);
  }

• src/tools/carbon-footprint-calculator.ts:1-215 (schema)

  Full tool definition including name, description, inputSchema (company profile, perimeter, scope sources, reduction targets, focus) and outputSchema (executiveSummary, totalEmissionsTco2eq, breakdown, hotspots, reductionLevers, sbtiTrajectory, scope3Categories, csrdReadiness, kpis).

  import { callGapupEndpoint } from "../client.js";
  
  export const tool = {
    name: "carbon_footprint_calculator",
    description:
      "Calculate a company's greenhouse-gas footprint under the GHG Protocol (Scope 1 + 2 + 3, in tCO2eq, tier-2 accuracy ±20%). Returns the emissions breakdown, hotspot identification, 5-8 reduction levers each with capex and payback, an SBTi-aligned reduction trajectory over 5-25 years, the 15 Scope-3 categories in detail, and CSRD/ESRS reporting readiness. When to use this tool: the user needs a carbon assessment for CSRD compliance pre-audit, green-finance access, or supplier ESG scorecards. Inputs: the company profile and its activity data. Delivered by Émilie, the AI Sustainability lead of the Gapup portfolio.",
    inputSchema: {
      type: "object",
      properties: {
        company: {
          type: "object",
          properties: {
            name: { type: "string", minLength: 2, maxLength: 120 },
            sector: { type: "string", minLength: 2, maxLength: 120 },
            fte: { type: "integer", minimum: 1 },
            revenueEur: { type: "number", minimum: 0 },
            locations: { type: "integer", minimum: 1 },
            referenceYear: { type: "integer", minimum: 2018, maximum: 2030 },
          },
          required: ["name", "sector", "fte", "referenceYear"],
        },
        perimeter: {
          type: "object",
          properties: {
            organizational: {
              type: "string",
              enum: ["operational-control", "financial-control", "equity-share"],
            },
            geographic: {
              type: "array",
              items: { type: "string" },
              minItems: 1,
              maxItems: 20,
            },
            excludedActivities: { type: "string", maxLength: 400 },
          },
          required: ["organizational", "geographic"],
        },
        scope1Sources: {
          type: "array",
          items: {
            type: "object",
            properties: {
              source: { type: "string", minLength: 2, maxLength: 120 },
              fuelType: { type: "string", minLength: 2, maxLength: 80 },
              annualConsumption: { type: "number", minimum: 0 },
              unit: { type: "string", maxLength: 40 },
            },
            required: ["source", "fuelType", "annualConsumption", "unit"],
          },
          maxItems: 15,
        },
        scope2Sources: {
          type: "array",
          items: {
            type: "object",
            properties: {
              source: { type: "string", minLength: 2, maxLength: 120 },
              energyType: { type: "string", enum: ["electricity", "heat", "steam", "cooling"] },
              annualConsumptionKWh: { type: "number", minimum: 0 },
              location: { type: "string", minLength: 2, maxLength: 80 },
              isRenewableContract: { type: "boolean" },
            },
            required: ["source", "energyType", "annualConsumptionKWh", "location", "isRenewableContract"],
          },
          minItems: 1,
          maxItems: 20,
        },
        scope3Activities: {
          type: "array",
          items: {
            type: "object",
            properties: {
              category: {
                type: "string",
                description: "GHG Protocol Scope 3 category 1-15",
              },
              description: { type: "string", minLength: 10, maxLength: 300 },
              estimatedScale: { type: "string", minLength: 4, maxLength: 120 },
            },
            required: ["category", "description"],
          },
          maxItems: 15,
        },
        reductionTargets: {
          type: "object",
          properties: {
            sbtiAligned: { type: "boolean" },
            targetYear: { type: "integer", minimum: 2025, maximum: 2050 },
            targetReductionPct: { type: "number", minimum: 0, maximum: 100 },
          },
          required: ["sbtiAligned", "targetYear", "targetReductionPct"],
        },
        focus: { type: "string", maxLength: 400 },
      },
      required: ["company", "perimeter", "scope2Sources"],
    },
    outputSchema: {
      type: "object",
      properties: {
        executiveSummary: {
          type: "string",
          description: "Board-ready GHG assessment prose",
        },
        totalEmissionsTco2eq: {
          type: "number",
          description: "Total GHG footprint in tCO2eq (Scope 1+2+3 combined, ±20% tier-2 accuracy)",
        },
        breakdown: {
          type: "object",
          description: "Emissions breakdown by scope",
          properties: {
            scope1Tco2eq: { type: "number" },
            scope2Tco2eq: { type: "number" },
            scope3Tco2eq: { type: "number" },
          },
          required: ["scope1Tco2eq", "scope2Tco2eq", "scope3Tco2eq"],
        },
        hotspots: {
          type: "array",
          description: "Top emission sources ranked by contribution",
          items: {
            type: "object",
            properties: {
              source: { type: "string" },
              scope: { type: "string", enum: ["1", "2", "3"] },
              emissionsTco2eq: { type: "number" },
              shareOfTotal: { type: "number", description: "Percentage of total footprint" },
            },
            required: ["source", "scope", "emissionsTco2eq"],
          },
        },
        reductionLevers: {
          type: "array",
          description: "5-8 actionable reduction levers with financial analysis",
          items: {
            type: "object",
            properties: {
              lever: { type: "string" },
              reductionPotentialTco2eq: { type: "number" },
              capexEur: { type: "number" },
              paybackYears: { type: "number" },
              priority: { type: "string", enum: ["high", "medium", "low"] },
            },
            required: ["lever", "reductionPotentialTco2eq"],
          },
        },
        sbtiTrajectory: {
          type: "array",
          description: "SBTi-aligned annual reduction trajectory",
          items: {
            type: "object",
            properties: {
              year: { type: "integer" },
              targetEmissionsTco2eq: { type: "number" },
              reductionVsBaselinePct: { type: "number" },
            },
            required: ["year", "targetEmissionsTco2eq"],
          },
        },
        scope3Categories: {
          type: "array",
          description: "GHG Protocol 15 Scope-3 categories detail",
          items: {
            type: "object",
            properties: {
              category: { type: "string" },
              categoryNumber: { type: "integer", minimum: 1, maximum: 15 },
              emissionsTco2eq: { type: "number" },
              dataQuality: { type: "string", enum: ["measured", "estimated", "excluded"] },
            },
            required: ["category", "emissionsTco2eq"],
          },
        },
        csrdReadiness: {
          type: "object",
          description: "CSRD/ESRS reporting readiness assessment",
          properties: {
            overallScore: { type: "number", minimum: 0, maximum: 100 },
            gaps: { type: "array", items: { type: "string" } },
            nextSteps: { type: "array", items: { type: "string" } },
          },
          required: ["overallScore"],
        },
        kpis: {
          type: "array",
          description: "3-5 headline ESG KPI bubbles",
          items: {
            type: "object",
            properties: {
              label: { type: "string" },
              value: { type: "string" },
              trend: { type: "string", enum: ["up", "down", "stable"] },
            },
            required: ["label", "value"],
          },
        },
      },
      required: [
        "executiveSummary",
        "totalEmissionsTco2eq",
        "breakdown",
        "hotspots",
        "reductionLevers",
        "csrdReadiness",
      ],
    },
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
      destructiveHint: false,
      openWorldHint: false,
      title: "Carbon Footprint Calculator (GHG Protocol)",
    },
  } as const;

• src/index.ts:25-41 (registration)

  Import and registration of the carbon footprint calculator tool in the main server. The tool and handler are imported and added to the TOOLS array used by the MCP server's ListToolsRequestSchema and CallToolRequestSchema handlers.

  import { tool as carbonTool, handle as carbonHandle } from "./tools/carbon-footprint-calculator.js";
  
  type ToolHandle = (input: unknown, signal?: AbortSignal) => Promise<unknown>;
  type ToolDef = {
    name: string;
    description: string;
    inputSchema: object;
    outputSchema?: object;
    annotations?: object;
  };
  
  const TOOLS: Array<{ def: ToolDef; handle: ToolHandle }> = [
    { def: competitorIntelTool, handle: competitorIntelHandle },
    { def: trendWatcherTool, handle: trendWatcherHandle },
    { def: partnershipTool, handle: partnershipHandle },
    { def: pitchDeckTool, handle: pitchDeckHandle },
    { def: carbonTool, handle: carbonHandle },

• src/client.ts:26-86 (helper)

  The callGapupEndpoint helper function that makes the HTTP POST request to the Gapup API hub. Handles auth, rate limiting, 402 payment required, and other error responses.

  export async function callGapupEndpoint(
    slug: string,
    input: unknown,
    signal?: AbortSignal
  ): Promise<unknown> {
    const apiKey = process.env.GAPUP_API_KEY;
    if (!apiKey) {
      throw new GapupAuthError(
        "GAPUP_API_KEY environment variable required. Get a free tier key (100 calls/mo) at https://hub.gapup.io/agents-api/onboard"
      );
    }
  
    const res = await fetch(`${HUB_BASE_URL}/api/agent/${slug}`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": apiKey,
        "Accept": "application/json",
        "User-Agent": "@gapup/mcp-knowledge/0.1.0",
      },
      body: JSON.stringify(input),
      signal,
    });
  
    if (res.status === 401) {
      throw new GapupAuthError(
        "Invalid or missing GAPUP_API_KEY. Verify your key at https://hub.gapup.io/agents-api/onboard"
      );
    }
  
    if (res.status === 402) {
      const body = await res.text().catch(() => "");
      throw new GapupAuthError(
        `Free tier quota exhausted or paid auth required. Upgrade at https://hub.gapup.io/agents-api (received 402: ${body.slice(0, 120)})`
      );
    }
  
    if (res.status === 404) {
      throw new GapupApiError(
        404,
        `Endpoint '${slug}' not found — check GAPUP_API_BASE_URL or update the package (npm update @gapup/mcp-knowledge)`
      );
    }
  
    if (res.status === 429) {
      const retryAfter = res.headers.get("Retry-After");
      const retryMsg = retryAfter ? ` Retry after ${retryAfter} seconds.` : "";
      const body = await res.text().catch(() => "");
      throw new GapupApiError(
        429,
        `Rate limit exceeded.${retryMsg} Upgrade your plan at https://hub.gapup.io/agents-api (received: ${body.slice(0, 100)})`
      );
    }
  
    if (!res.ok) {
      const body = await res.text().catch(() => "");
      throw new GapupApiError(res.status, body);
    }
  
    return res.json();
  }