@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/fingrid.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const API_BASE = "https://data.fingrid.fi/api/datasets";
+const cache = new TtlCache();
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+const PAGE_SIZE = 200;
+/** Fingrid dataset IDs */
+const DATASET_IDS = {
+    consumption: 124,
+    production: 74,
+    wind_production: 75,
+    solar_production: 248,
+    nuclear_production: 188,
+    hydro_production: 191,
+    imports: 87,
+    exports: 89,
+    frequency: 177,
+    reserve_prices: 244,
+};
+export const fingridSchema = z.object({
+    dataset: z
+        .enum([
+        "consumption",
+        "production",
+        "wind_production",
+        "solar_production",
+        "nuclear_production",
+        "hydro_production",
+        "imports",
+        "exports",
+        "frequency",
+        "reserve_prices",
+    ])
+        .describe('"consumption" = Finnish electricity consumption (MW, 3-min). ' +
+        '"production" = total electricity production (MW, 3-min). ' +
+        '"wind_production" = wind power generation (MW, 3-min). ' +
+        '"solar_production" = solar power estimate (MW). ' +
+        '"nuclear_production" = nuclear generation (MW, hourly). ' +
+        '"hydro_production" = hydro generation (MW, hourly). ' +
+        '"imports" = electricity imports to Finland (MW). ' +
+        '"exports" = electricity exports from Finland (MW). ' +
+        '"frequency" = grid frequency measurements (Hz, 3-min). ' +
+        '"reserve_prices" = balancing reserve market prices.'),
+    start_date: z
+        .string()
+        .optional()
+        .describe("Start datetime ISO-8601 (e.g. 2025-01-15T00:00:00Z). Defaults to 24h ago."),
+    end_date: z
+        .string()
+        .optional()
+        .describe("End datetime ISO-8601. Defaults to now."),
+});
+async function getApiKey() {
+    try {
+        return await resolveApiKey("FINGRID_API_KEY");
+    }
+    catch {
+        throw new Error("FINGRID_API_KEY is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Get one free at https://data.fingrid.fi/ (register for API access).");
+    }
+}
+const UNITS = {
+    consumption: "MW",
+    production: "MW",
+    wind_production: "MW",
+    solar_production: "MW",
+    nuclear_production: "MW",
+    hydro_production: "MW",
+    imports: "MW",
+    exports: "MW",
+    frequency: "Hz",
+    reserve_prices: "EUR/MW",
+};
+function alignToBucket(date, bucketMs) {
+    return new Date(Math.floor(date.getTime() / bucketMs) * bucketMs);
+}
+function getEffectiveWindow(params) {
+    if (params.start_date && params.end_date) {
+        return { startDate: params.start_date, endDate: params.end_date };
+    }
+    const alignedNow = alignToBucket(new Date(), TTL.REALTIME);
+    const alignedDayAgo = new Date(alignedNow.getTime() - DEFAULT_WINDOW_MS);
+    return {
+        startDate: params.start_date ?? alignedDayAgo.toISOString(),
+        endDate: params.end_date ?? alignedNow.toISOString(),
+    };
+}
+function buildPageUrl(datasetId, startDate, endDate, page) {
+    return (`${API_BASE}/${datasetId}/data?startTime=${encodeURIComponent(startDate)}` +
+        `&endTime=${encodeURIComponent(endDate)}&format=json&pageSize=${PAGE_SIZE}&page=${page}`);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractRows(json) {
+    return Array.isArray(json?.data) ? json.data : Array.isArray(json) ? json : [];
+}
+async function fetchAllRows(datasetId, startDate, endDate, apiKey) {
+    const rows = [];
+    for (let page = 1; page <= 50; page++) {
+        const url = buildPageUrl(datasetId, startDate, endDate, page);
+        const response = await fetch(url, {
+            headers: {
+                "x-api-key": apiKey,
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Fingrid API returned ${response.status}: ${body.slice(0, 300)}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const json = await response.json();
+        const pageRows = extractRows(json);
+        rows.push(...pageRows.map((r) => ({
+            timestamp: r.startTime ?? r.start_time ?? r.timestamp ?? "",
+            value: Math.round(Number(r.value ?? 0) * 100) / 100,
+        })));
+        if (pageRows.length < PAGE_SIZE) {
+            break;
+        }
+    }
+    return rows
+        .filter((row) => row.timestamp)
+        .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+export async function getFingridData(params) {
+    const apiKey = await getApiKey();
+    const datasetId = DATASET_IDS[params.dataset];
+    const unit = UNITS[params.dataset] ?? "MW";
+    const { startDate, endDate } = getEffectiveWindow(params);
+    const cacheKey = `fingrid:${datasetId}:${startDate}:${endDate}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const data = await fetchAllRows(datasetId, startDate, endDate, apiKey);
+    const values = data.map((d) => d.value);
+    const stats = values.length > 0
+        ? {
+            min: Math.round(Math.min(...values) * 100) / 100,
+            max: Math.round(Math.max(...values) * 100) / 100,
+            mean: Math.round((values.reduce((s, v) => s + v, 0) / values.length) * 100) / 100,
+        }
+        : null;
+    const result = {
+        source: "Fingrid Open Data",
+        dataset: params.dataset,
+        dataset_id: datasetId,
+        unit,
+        start_date: startDate,
+        end_date: endDate,
+        count: data.length,
+        latest: data.length > 0 ? data[data.length - 1] : null,
+        data,
+        stats,
+    };
+    cache.set(cacheKey, result, TTL.REALTIME);
+    return result;
+}

package/dist/tools/flood-risk.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { type GisSourceMetadata } from "../lib/gis-sources.js";
+export declare const floodRiskSchema: z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    country: z.ZodString;
+}, z.core.$strip>;
+type FloodZone = "1" | "2" | "3" | "unknown";
+type PlanningRisk = "low" | "medium" | "high" | "unknown";
+type FloodLayerKey = "flood_storage_area" | "flood_zone_3" | "flood_zone_2";
+interface FloodMatch {
+    layer: FloodLayerKey;
+    label: string;
+    type: string | null;
+    area_ha: number | null;
+}
+interface FloodRiskResult {
+    lat: number;
+    lon: number;
+    country: string;
+    flood_zone: FloodZone;
+    flood_storage_area: boolean;
+    planning_risk: PlanningRisk;
+    flood_zone_3: FloodMatch[];
+    flood_zone_2: FloodMatch[];
+    flood_storage_areas: FloodMatch[];
+    explanation: string;
+    source_metadata: GisSourceMetadata;
+    warnings?: string[];
+    disclaimer: string;
+}
+export declare function getFloodRisk(params: z.infer<typeof floodRiskSchema>): Promise<FloodRiskResult>;
+export {};

package/dist/tools/flood-risk.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { GIS_SOURCES } from "../lib/gis-sources.js";
+import { guardArcGisFields } from "../lib/schema-guard.js";
+const cache = new TtlCache();
+const EA_FLOOD_MAP_BASE = "https://environment.data.gov.uk/KB6uNVj5ZcJr7jUP/ArcGIS/rest/services/Flood_Map_for_Planning/FeatureServer";
+export const floodRiskSchema = z.object({
+    lat: z.number().describe("Latitude (-90 to 90). WGS84."),
+    lon: z.number().describe("Longitude (-180 to 180). WGS84."),
+    country: z
+        .string()
+        .describe('ISO 3166-1 alpha-2 country code. Only "GB" is supported in this version.'),
+});
+const DISCLAIMER = "This is an automated flood-planning screen using the Environment Agency Flood Map for Planning. " +
+    "It is not a site-specific flood risk assessment or planning determination.";
+const FLOOD_LAYERS = [
+    { id: 0, key: "flood_storage_area", label: "Flood Storage Areas" },
+    { id: 1, key: "flood_zone_3", label: "Flood Zone 3" },
+    { id: 2, key: "flood_zone_2", label: "Flood Zone 2" },
+];
+function buildPointQueryUrl(layerId, lon, lat) {
+    const url = new URL(`${EA_FLOOD_MAP_BASE}/${layerId}/query`);
+    const p = url.searchParams;
+    p.set("where", "1=1");
+    p.set("geometry", `${lon},${lat}`);
+    p.set("geometryType", "esriGeometryPoint");
+    p.set("inSR", "4326");
+    p.set("spatialRel", "esriSpatialRelIntersects");
+    p.set("outFields", "layer,type,Shape__Area");
+    p.set("returnGeometry", "false");
+    p.set("resultRecordCount", "10");
+    p.set("f", "json");
+    return url.toString();
+}
+async function queryLayer(layer, lon, lat) {
+    const response = await fetch(buildPointQueryUrl(layer.id, lon, lat));
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Environment Agency Flood Map API returned ${response.status} for ${layer.label}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`Environment Agency Flood Map API error for ${layer.label}: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    const features = Array.isArray(json.features) ? json.features : [];
+    guardArcGisFields(features, ["layer", "Shape__Area"], `Environment Agency Flood Map (${layer.label})`);
+    return features;
+}
+function toRoundedHectares(value) {
+    if (typeof value !== "number")
+        return null;
+    return Math.round((value / 10_000) * 100) / 100;
+}
+function toOptionalString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function mapMatches(layer, features) {
+    return features.map((feature) => {
+        const attrs = feature.attributes ?? {};
+        return {
+            layer: layer.key,
+            label: toOptionalString(attrs.layer) ?? layer.label,
+            type: toOptionalString(attrs.type),
+            area_ha: toRoundedHectares(attrs.Shape__Area),
+        };
+    });
+}
+function buildExplanation(floodZone, hasFloodStorageArea, planningRisk) {
+    if (hasFloodStorageArea && floodZone === "3") {
+        return "Point intersects a flood storage area and Flood Zone 3. Treat this as a high planning-risk site for development screening.";
+    }
+    if (hasFloodStorageArea && floodZone === "2") {
+        return "Point intersects a flood storage area and Flood Zone 2. Treat this as a high planning-risk site for development screening.";
+    }
+    if (hasFloodStorageArea) {
+        return "Point intersects a flood storage area. Treat this as a high planning-risk site for development screening.";
+    }
+    if (floodZone === "3") {
+        return "Point is in Flood Zone 3, the high-probability flood zone in the Environment Agency Flood Map for Planning.";
+    }
+    if (floodZone === "2") {
+        return "Point is in Flood Zone 2, but not Flood Zone 3, in the Environment Agency Flood Map for Planning.";
+    }
+    if (floodZone === "1" && planningRisk === "low") {
+        return "Point does not intersect Flood Zone 2, Flood Zone 3, or a flood storage area in the Environment Agency Flood Map for Planning.";
+    }
+    return "Flood classification is unknown because one or more Environment Agency flood layers could not be checked.";
+}
+export async function getFloodRisk(params) {
+    const { lat, lon } = params;
+    const country = params.country.toUpperCase();
+    if (country !== "GB") {
+        throw new Error(`Country "${params.country}" is not supported. Only "GB" (Great Britain) is available in this version. England flood-planning coverage is implemented first via the Environment Agency Flood Map for Planning.`);
+    }
+    if (lat < -90 || lat > 90) {
+        throw new Error("Latitude must be between -90 and 90.");
+    }
+    if (lon < -180 || lon > 180) {
+        throw new Error("Longitude must be between -180 and 180.");
+    }
+    const cacheKey = `flood-risk:${lat}:${lon}:${country}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const results = await Promise.allSettled(FLOOD_LAYERS.map((layer) => queryLayer(layer, lon, lat)));
+    const warnings = [];
+    const storageAreas = results[0].status === "fulfilled" ? mapMatches(FLOOD_LAYERS[0], results[0].value) : [];
+    if (results[0].status === "rejected") {
+        warnings.push(`flood_storage_area: ${results[0].reason instanceof Error ? results[0].reason.message : String(results[0].reason)}`);
+    }
+    const zone3 = results[1].status === "fulfilled" ? mapMatches(FLOOD_LAYERS[1], results[1].value) : [];
+    if (results[1].status === "rejected") {
+        warnings.push(`flood_zone_3: ${results[1].reason instanceof Error ? results[1].reason.message : String(results[1].reason)}`);
+    }
+    const zone2 = results[2].status === "fulfilled" ? mapMatches(FLOOD_LAYERS[2], results[2].value) : [];
+    if (results[2].status === "rejected") {
+        warnings.push(`flood_zone_2: ${results[2].reason instanceof Error ? results[2].reason.message : String(results[2].reason)}`);
+    }
+    if (results.every((result) => result.status === "rejected")) {
+        throw new Error(`All Environment Agency flood queries failed: ${warnings.join("; ")}`);
+    }
+    const hasFloodStorageArea = storageAreas.length > 0;
+    const hasZone3 = zone3.length > 0;
+    const hasZone2 = zone2.length > 0;
+    const hasWarnings = warnings.length > 0;
+    let floodZone = "1";
+    let planningRisk = "low";
+    if (hasZone3) {
+        floodZone = "3";
+        planningRisk = "high";
+    }
+    else if (hasZone2) {
+        floodZone = "2";
+        planningRisk = "medium";
+    }
+    else if (hasWarnings) {
+        floodZone = "unknown";
+        planningRisk = "unknown";
+    }
+    if (hasFloodStorageArea) {
+        planningRisk = "high";
+    }
+    const result = {
+        lat,
+        lon,
+        country: "GB",
+        flood_zone: floodZone,
+        flood_storage_area: hasFloodStorageArea,
+        planning_risk: planningRisk,
+        flood_zone_3: zone3,
+        flood_zone_2: zone2,
+        flood_storage_areas: storageAreas,
+        explanation: buildExplanation(floodZone, hasFloodStorageArea, planningRisk),
+        source_metadata: GIS_SOURCES["ea-flood-map"],
+        disclaimer: DISCLAIMER,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    cache.set(cacheKey, result, TTL.STATIC_DATA);
+    return result;
+}

package/dist/tools/flows.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const flowsSchema: z.ZodObject<{
+    from_zone: z.ZodString;
+    to_zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface FlowPoint {
+    hour: number;
+    mw: number;
+}
+export declare function getCrossBorderFlows(params: z.infer<typeof flowsSchema>): Promise<{
+    from_zone: string;
+    to_zone: string;
+    date: string;
+    flows: FlowPoint[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+        net_mwh: number;
+    };
+}>;
+export {};

package/dist/tools/flows.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { queryEntsoe, dayRange } from "../lib/entsoe-client.js";
+import { resolveZone, AVAILABLE_ZONES } from "../lib/zone-codes.js";
+import { ensureArray } from "../lib/xml-parser.js";
+import { TTL } from "../lib/cache.js";
+export const flowsSchema = z.object({
+    from_zone: z
+        .string()
+        .describe(`Exporting zone. Examples: FR, DE. Available: ${AVAILABLE_ZONES}`),
+    to_zone: z
+        .string()
+        .describe(`Importing zone. Examples: DE, GB. Available: ${AVAILABLE_ZONES}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+export async function getCrossBorderFlows(params) {
+    const fromEic = resolveZone(params.from_zone);
+    const toEic = resolveZone(params.to_zone);
+    const { periodStart, periodEnd } = dayRange(params.date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = await queryEntsoe({
+        documentType: "A11",
+        in_Domain: toEic,
+        out_Domain: fromEic,
+        periodStart,
+        periodEnd,
+    }, TTL.FLOWS);
+    const doc = data.GL_MarketDocument;
+    if (!doc)
+        throw new Error("No flow data returned for this corridor/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const flows = [];
+    for (const ts of timeSeries) {
+        const periods = ensureArray(ts.Period);
+        for (const period of periods) {
+            const points = ensureArray(period.Point);
+            for (const point of points) {
+                const position = Number(point.position);
+                const mw = Number(point.quantity);
+                flows.push({ hour: position - 1, mw });
+            }
+        }
+    }
+    flows.sort((a, b) => a.hour - b.hour);
+    const values = flows.map((f) => f.mw);
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const mean = values.length > 0
+        ? Math.round((values.reduce((s, v) => s + v, 0) / values.length) * 100) / 100
+        : 0;
+    const net_mwh = values.reduce((s, v) => s + v, 0);
+    return {
+        from_zone: params.from_zone.toUpperCase(),
+        to_zone: params.to_zone.toUpperCase(),
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        flows,
+        stats: { min, max, mean, net_mwh },
+    };
+}

package/dist/tools/frequency.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const frequencySchema: z.ZodObject<{}, z.core.$strip>;
+interface FrequencyResult {
+    frequency_hz: number;
+    deviation_mhz: number;
+    timestamp: string;
+    status: string;
+}
+export declare function getEuFrequency(_params: z.infer<typeof frequencySchema>): Promise<FrequencyResult>;
+export {};

package/dist/tools/frequency.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const API_URL = "https://www.mainsfrequency.com/api.php?unit=mHz";
+const cache = new TtlCache();
+export const frequencySchema = z.object({});
+export async function getEuFrequency(_params) {
+    const cacheKey = "eu-frequency";
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const response = await fetch(API_URL);
+    if (!response.ok) {
+        throw new Error(`Frequency API returned ${response.status}`);
+    }
+    const text = await response.text();
+    const mhz = Number(text.trim());
+    if (isNaN(mhz)) {
+        throw new Error(`Unexpected frequency API response: ${text.slice(0, 100)}`);
+    }
+    const frequencyHz = mhz / 1000;
+    const nominalHz = 50.0;
+    const deviationMhz = mhz - nominalHz * 1000;
+    const status = Math.abs(deviationMhz) <= 20 ? "normal" :
+        Math.abs(deviationMhz) <= 50 ? "minor deviation" :
+            Math.abs(deviationMhz) <= 100 ? "significant deviation" :
+                "critical deviation";
+    const result = {
+        frequency_hz: Math.round(frequencyHz * 1000) / 1000,
+        deviation_mhz: Math.round(deviationMhz),
+        timestamp: new Date().toISOString(),
+        status,
+    };
+    cache.set(cacheKey, result, TTL.FREQUENCY);
+    return result;
+}

package/dist/tools/gas-storage.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const gasStorageSchema: z.ZodObject<{
+    country: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface StorageData {
+    country: string;
+    date: string;
+    gas_in_storage_twh: number;
+    full_pct: number;
+    injection_gwh: number;
+    withdrawal_gwh: number;
+    net_gwh: number;
+    trend_vs_last_year_pct: number | null;
+    working_volume_twh: number;
+}
+export declare function getGasStorage(params: z.infer<typeof gasStorageSchema>): Promise<StorageData>;
+export {};

package/dist/tools/gas-storage.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const BASE_URL = "https://agsi.gie.eu/api";
+const cache = new TtlCache();
+const GIE_COUNTRIES = [
+    "EU", "AT", "BE", "BG", "HR", "CZ", "DK", "FR", "DE",
+    "HU", "IE", "IT", "LV", "NL", "PL", "PT", "RO", "SK", "ES", "SE", "GB",
+];
+export const gasStorageSchema = z.object({
+    country: z
+        .string()
+        .describe(`Country code for gas storage data. Available: ${GIE_COUNTRIES.join(", ")}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+async function getApiKey() {
+    try {
+        return await resolveApiKey("GIE_API_KEY");
+    }
+    catch {
+        throw new Error("GIE_API_KEY is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Get one at https://agsi.gie.eu/ (register for API access).");
+    }
+}
+function validateCountry(code) {
+    const upper = code.toUpperCase();
+    if (!GIE_COUNTRIES.includes(upper)) {
+        throw new Error(`Unknown country "${code}". Available: ${GIE_COUNTRIES.join(", ")}`);
+    }
+    return upper;
+}
+export async function getGasStorage(params) {
+    const country = validateCountry(params.country);
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    const cacheKey = `gie:${country}:${date}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const url = `${BASE_URL}/data/${country}?date=${date}`;
+    const response = await fetch(url, {
+        headers: { "x-key": await getApiKey() },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`GIE API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    // AGSI+ returns { data: [...] } with storage entries
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const entries = Array.isArray(json.data) ? json.data : [];
+    if (entries.length === 0) {
+        throw new Error(`No gas storage data for ${country} on ${date}.`);
+    }
+    // First entry is the aggregate for the country
+    const entry = entries[0];
+    const result = {
+        country,
+        date: entry.gasDayStart ?? date,
+        gas_in_storage_twh: Number(entry.gasInStorage ?? 0),
+        full_pct: Number(entry.full ?? 0),
+        injection_gwh: Number(entry.injection ?? 0),
+        withdrawal_gwh: Number(entry.withdrawal ?? 0),
+        net_gwh: Number(entry.netWithdrawal ?? 0),
+        trend_vs_last_year_pct: entry.trend != null ? Number(entry.trend) : null,
+        working_volume_twh: Number(entry.workingGasVolume ?? 0),
+    };
+    cache.set(cacheKey, result, TTL.STORAGE);
+    return result;
+}

package/dist/tools/generation.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const generationSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface GenerationEntry {
+    fuel_type: string;
+    psr_code: string;
+    mw: number;
+}
+export declare function getGenerationMix(params: z.infer<typeof generationSchema>): Promise<{
+    zone: string;
+    date: string;
+    generation: GenerationEntry[];
+    total_mw: number;
+}>;
+export {};

package/dist/tools/generation.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { queryEntsoe, dayRange } from "../lib/entsoe-client.js";
+import { resolveZone, AVAILABLE_ZONES } from "../lib/zone-codes.js";
+import { ensureArray } from "../lib/xml-parser.js";
+import { TTL } from "../lib/cache.js";
+export const generationSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Country/zone code. Examples: DE, FR, GB, NL, ES. Available: ${AVAILABLE_ZONES}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+/** ENTSO-E PSR type codes to human-readable fuel names */
+const PSR_TYPES = {
+    B01: "Biomass",
+    B02: "Fossil Brown coal/Lignite",
+    B03: "Fossil Coal-derived gas",
+    B04: "Fossil Gas",
+    B05: "Fossil Hard coal",
+    B06: "Fossil Oil",
+    B07: "Fossil Oil shale",
+    B08: "Fossil Peat",
+    B09: "Geothermal",
+    B10: "Hydro Pumped Storage",
+    B11: "Hydro Run-of-river and poundage",
+    B12: "Hydro Water Reservoir",
+    B13: "Marine",
+    B14: "Nuclear",
+    B15: "Other renewable",
+    B16: "Solar",
+    B17: "Waste",
+    B18: "Wind Offshore",
+    B19: "Wind Onshore",
+    B20: "Other",
+};
+export async function getGenerationMix(params) {
+    const eic = resolveZone(params.zone);
+    const { periodStart, periodEnd } = dayRange(params.date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = await queryEntsoe({
+        documentType: "A75",
+        processType: "A16",
+        in_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.REALTIME);
+    const doc = data.GL_MarketDocument;
+    if (!doc)
+        throw new Error("No generation data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const generation = [];
+    for (const ts of timeSeries) {
+        const psrCode = ts.MktPSRType?.psrType ?? "unknown";
+        const fuelType = PSR_TYPES[psrCode] ?? psrCode;
+        const periods = ensureArray(ts.Period);
+        // Take the latest period's points and average them
+        const lastPeriod = periods[periods.length - 1];
+        if (!lastPeriod)
+            continue;
+        const points = ensureArray(lastPeriod.Point);
+        if (points.length === 0)
+            continue;
+        // Use the most recent point's quantity
+        const latestPoint = points[points.length - 1];
+        const mw = Number(latestPoint["quantity"] ?? 0);
+        if (mw > 0) {
+            generation.push({ fuel_type: fuelType, psr_code: psrCode, mw });
+        }
+    }
+    generation.sort((a, b) => b.mw - a.mw);
+    const total_mw = generation.reduce((sum, g) => sum + g.mw, 0);
+    return {
+        zone: params.zone.toUpperCase(),
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        generation,
+        total_mw,
+    };
+}