@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/entsog.d.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export declare const entsogSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        capacities: "capacities";
+        physical_flows: "physical_flows";
+        nominations: "nominations";
+        interruptions: "interruptions";
+    }>;
+    country: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface FlowRecord {
+    point_label: string;
+    operator: string;
+    direction: string;
+    flow_gwh: number;
+    date: string;
+}
+interface FlowsResult {
+    dataset: "physical_flows";
+    source: string;
+    date: string;
+    country: string | null;
+    records: FlowRecord[];
+}
+interface NominationRecord {
+    point_label: string;
+    operator: string;
+    direction: string;
+    nominated_gwh: number;
+    date: string;
+}
+interface NominationsResult {
+    dataset: "nominations";
+    source: string;
+    date: string;
+    country: string | null;
+    records: NominationRecord[];
+}
+interface InterruptionRecord {
+    point_label: string;
+    operator: string;
+    type: string;
+    start: string;
+    end: string;
+    affected_capacity_gwh: number;
+}
+interface InterruptionsResult {
+    dataset: "interruptions";
+    source: string;
+    country: string | null;
+    records: InterruptionRecord[];
+}
+interface CapacityRecord {
+    point_label: string;
+    operator: string;
+    direction: string;
+    technical_gwh: number;
+    booked_gwh: number;
+    available_gwh: number;
+}
+interface CapacitiesResult {
+    dataset: "capacities";
+    source: string;
+    date: string;
+    country: string | null;
+    records: CapacityRecord[];
+}
+type EntsogResult = FlowsResult | NominationsResult | InterruptionsResult | CapacitiesResult;
+export declare function getEntsogData(params: z.infer<typeof entsogSchema>): Promise<EntsogResult>;
+export {};

package/dist/tools/entsog.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const API_BASE = "https://transparency.entsog.eu/api/v1";
+const cache = new TtlCache();
+export const entsogSchema = z.object({
+    dataset: z
+        .enum(["physical_flows", "nominations", "interruptions", "capacities"])
+        .describe('"physical_flows" = actual gas pipeline flows (GWh/d) between points. ' +
+        '"nominations" = day-ahead nominated gas volumes. ' +
+        '"interruptions" = pipeline capacity interruptions and maintenance. ' +
+        '"capacities" = technical/booked/available pipeline capacities.'),
+    country: z
+        .string()
+        .optional()
+        .describe("ISO-2 country code to filter by operator country (e.g. DE, NL, AT, FR, IT, PL). Optional."),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to yesterday."),
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function fetchEntsog(endpoint, params) {
+    const query = new URLSearchParams({ ...params, limit: "100" });
+    const url = `${API_BASE}/${endpoint}?${query}`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = await fetch(url, {
+        headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`ENTSOG API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(url, json, TTL.FLOWS);
+    return json;
+}
+function yesterday() {
+    const d = new Date();
+    d.setDate(d.getDate() - 1);
+    return d.toISOString().slice(0, 10);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseFlows(data, date, country) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const points = Array.isArray(data?.physicalflows) ? data.physicalflows : [];
+    const records = points.slice(0, 50).map((p) => ({
+        point_label: p.pointLabel ?? p.pointKey ?? "Unknown",
+        operator: p.operatorLabel ?? p.operatorKey ?? "Unknown",
+        direction: p.directionKey ?? "unknown",
+        flow_gwh: Math.round((Number(p.value ?? 0)) * 100) / 100,
+        date: p.periodFrom ?? date,
+    }));
+    return {
+        dataset: "physical_flows",
+        source: "ENTSOG Transparency Platform",
+        date,
+        country,
+        records,
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseNominations(data, date, country) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const points = Array.isArray(data?.nominations) ? data.nominations : [];
+    const records = points.slice(0, 50).map((p) => ({
+        point_label: p.pointLabel ?? p.pointKey ?? "Unknown",
+        operator: p.operatorLabel ?? p.operatorKey ?? "Unknown",
+        direction: p.directionKey ?? "unknown",
+        nominated_gwh: Math.round((Number(p.value ?? 0)) * 100) / 100,
+        date: p.periodFrom ?? date,
+    }));
+    return {
+        dataset: "nominations",
+        source: "ENTSOG Transparency Platform",
+        date,
+        country,
+        records,
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseInterruptions(data, country) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const items = Array.isArray(data?.interruptions) ? data.interruptions : [];
+    const records = items.slice(0, 50).map((i) => ({
+        point_label: i.pointLabel ?? i.pointKey ?? "Unknown",
+        operator: i.operatorLabel ?? i.operatorKey ?? "Unknown",
+        type: i.type ?? "unknown",
+        start: i.periodFrom ?? "",
+        end: i.periodTo ?? "",
+        affected_capacity_gwh: Math.round((Number(i.value ?? 0)) * 100) / 100,
+    }));
+    return {
+        dataset: "interruptions",
+        source: "ENTSOG Transparency Platform",
+        country,
+        records,
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function parseCapacities(data, date, country) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const items = Array.isArray(data?.operationaldatas) ? data.operationaldatas : [];
+    const records = items.slice(0, 50).map((c) => ({
+        point_label: c.pointLabel ?? c.pointKey ?? "Unknown",
+        operator: c.operatorLabel ?? c.operatorKey ?? "Unknown",
+        direction: c.directionKey ?? "unknown",
+        technical_gwh: Math.round((Number(c.technicalCapacity ?? 0)) * 100) / 100,
+        booked_gwh: Math.round((Number(c.bookedCapacity ?? 0)) * 100) / 100,
+        available_gwh: Math.round((Number(c.availableCapacity ?? 0)) * 100) / 100,
+    }));
+    return {
+        dataset: "capacities",
+        source: "ENTSOG Transparency Platform",
+        date,
+        country,
+        records,
+    };
+}
+export async function getEntsogData(params) {
+    const date = params.date ?? yesterday();
+    const country = params.country?.toUpperCase() ?? null;
+    const baseParams = {
+        from: date,
+        to: date,
+        periodType: "day",
+        indicator: "Physical Flow",
+    };
+    if (country) {
+        baseParams.operatorCountry = country;
+    }
+    switch (params.dataset) {
+        case "physical_flows": {
+            baseParams.indicator = "Physical Flow";
+            const data = await fetchEntsog("operationaldatas", baseParams);
+            return parseFlows(data, date, country);
+        }
+        case "nominations": {
+            baseParams.indicator = "Nomination";
+            const data = await fetchEntsog("nominationdatas", baseParams);
+            return parseNominations(data, date, country);
+        }
+        case "interruptions": {
+            const data = await fetchEntsog("interruptions", {
+                from: date,
+                to: date,
+                ...(country ? { operatorCountry: country } : {}),
+                limit: "50",
+            });
+            return parseInterruptions(data, country);
+        }
+        case "capacities": {
+            baseParams.indicator = "Physical Flow";
+            const data = await fetchEntsog("operationaldatas", baseParams);
+            return parseCapacities(data, date, country);
+        }
+    }
+}

package/dist/tools/era5-weather.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export declare const era5WeatherSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    start_date: z.ZodString;
+    end_date: z.ZodString;
+    variables: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        wind: "wind";
+        solar: "solar";
+        temperature: "temperature";
+    }>>;
+}, z.core.$strip>;
+interface HourlyEntry {
+    timestamp: string;
+    [key: string]: string | number | null;
+}
+interface Era5Result {
+    source: string;
+    latitude: number;
+    longitude: number;
+    start_date: string;
+    end_date: string;
+    variables: string[];
+    hourly_count: number;
+    hourly: HourlyEntry[];
+    daily_summary: DailySummary[];
+}
+interface DailySummary {
+    date: string;
+    temp_mean_c: number | null;
+    temp_min_c: number | null;
+    temp_max_c: number | null;
+    wind_10m_mean_ms: number | null;
+    wind_100m_mean_ms: number | null;
+    ghi_wh_m2: number | null;
+}
+export declare function getEra5Weather(params: z.infer<typeof era5WeatherSchema>): Promise<Era5Result>;
+export {};

package/dist/tools/era5-weather.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const API_BASE = "https://archive-api.open-meteo.com/v1/archive";
+const cache = new TtlCache();
+export const era5WeatherSchema = z.object({
+    latitude: z.number().describe("Latitude (-90 to 90)."),
+    longitude: z.number().describe("Longitude (-180 to 180)."),
+    start_date: z
+        .string()
+        .describe("Start date YYYY-MM-DD. ERA5 data available from 1940."),
+    end_date: z
+        .string()
+        .describe("End date YYYY-MM-DD. Usually available up to 5 days ago."),
+    variables: z
+        .enum(["wind", "solar", "temperature", "all"])
+        .optional()
+        .describe('"wind" = wind speed at 10m and 100m hub height. ' +
+        '"solar" = GHI, DNI, diffuse radiation. ' +
+        '"temperature" = 2m temperature, dewpoint, soil temperature. ' +
+        '"all" = all variables (default).'),
+});
+function getHourlyParams(variables) {
+    const wind = "windspeed_10m,windspeed_100m,winddirection_10m,winddirection_100m";
+    const solar = "shortwave_radiation,direct_radiation,diffuse_radiation,direct_normal_irradiance";
+    const temp = "temperature_2m,dewpoint_2m,soil_temperature_0cm";
+    switch (variables) {
+        case "wind":
+            return wind;
+        case "solar":
+            return solar;
+        case "temperature":
+            return temp;
+        default:
+            return `${temp},${wind},${solar}`;
+    }
+}
+export async function getEra5Weather(params) {
+    const vars = params.variables ?? "all";
+    const hourlyParams = getHourlyParams(vars);
+    const url = `${API_BASE}?latitude=${params.latitude}&longitude=${params.longitude}` +
+        `&start_date=${params.start_date}&end_date=${params.end_date}` +
+        `&hourly=${hourlyParams}&timezone=UTC`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = await fetch(url);
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Open-Meteo Archive API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    const hourlyData = json.hourly ?? {};
+    const times = hourlyData.time ?? [];
+    // Build hourly entries (cap at 168 = 7 days of hourly)
+    const maxEntries = Math.min(times.length, 168);
+    const hourly = [];
+    for (let i = 0; i < maxEntries; i++) {
+        const entry = { timestamp: times[i] };
+        for (const [key, values] of Object.entries(hourlyData)) {
+            if (key === "time")
+                continue;
+            const arr = values;
+            entry[key] = arr[i] ?? null;
+        }
+        hourly.push(entry);
+    }
+    // Build daily summaries
+    const dailyMap = new Map();
+    for (let i = 0; i < times.length; i++) {
+        const date = times[i].slice(0, 10);
+        if (!dailyMap.has(date)) {
+            dailyMap.set(date, { temps: [], wind10: [], wind100: [], ghi: [] });
+        }
+        const bucket = dailyMap.get(date);
+        const temp = hourlyData.temperature_2m?.[i];
+        if (temp != null)
+            bucket.temps.push(temp);
+        const w10 = hourlyData.windspeed_10m?.[i];
+        if (w10 != null)
+            bucket.wind10.push(w10);
+        const w100 = hourlyData.windspeed_100m?.[i];
+        if (w100 != null)
+            bucket.wind100.push(w100);
+        const ghi = hourlyData.shortwave_radiation?.[i];
+        if (ghi != null)
+            bucket.ghi.push(ghi);
+    }
+    const dailySummary = [];
+    for (const [date, bucket] of dailyMap.entries()) {
+        const avg = (arr) => arr.length > 0 ? Math.round((arr.reduce((s, v) => s + v, 0) / arr.length) * 10) / 10 : null;
+        const sum = (arr) => arr.length > 0 ? Math.round(arr.reduce((s, v) => s + v, 0)) : null;
+        dailySummary.push({
+            date,
+            temp_mean_c: avg(bucket.temps),
+            temp_min_c: bucket.temps.length > 0 ? Math.round(Math.min(...bucket.temps) * 10) / 10 : null,
+            temp_max_c: bucket.temps.length > 0 ? Math.round(Math.max(...bucket.temps) * 10) / 10 : null,
+            wind_10m_mean_ms: avg(bucket.wind10),
+            wind_100m_mean_ms: avg(bucket.wind100),
+            ghi_wh_m2: sum(bucket.ghi),
+        });
+    }
+    const variableNames = Object.keys(hourlyData).filter((k) => k !== "time");
+    const result = {
+        source: "Open-Meteo Archive (ERA5 reanalysis, Copernicus/ECMWF)",
+        latitude: json.latitude ?? params.latitude,
+        longitude: json.longitude ?? params.longitude,
+        start_date: params.start_date,
+        end_date: params.end_date,
+        variables: variableNames,
+        hourly_count: times.length,
+        hourly,
+        daily_summary: dailySummary,
+    };
+    cache.set(url, result, TTL.WEATHER);
+    return result;
+}

package/dist/tools/eu-gas-price.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/**
+ * Fetches European natural gas prices from multiple free sources.
+ * Primary: Yahoo Finance TTF futures (no API key needed).
+ * Fallback: Derives from GIE AGSI+ storage economics if available.
+ */
+export declare const euGasPriceSchema: z.ZodObject<{
+    hub: z.ZodOptional<z.ZodEnum<{
+        ttf: "ttf";
+        nbp: "nbp";
+    }>>;
+    period: z.ZodOptional<z.ZodEnum<{
+        spot: "spot";
+        week: "week";
+    }>>;
+}, z.core.$strip>;
+interface GasPricePoint {
+    date: string;
+    price: number;
+    currency: string;
+    unit: string;
+}
+interface EuGasPriceResult {
+    hub: string;
+    hub_name: string;
+    currency: string;
+    unit: string;
+    latest: GasPricePoint;
+    prices: GasPricePoint[];
+    price_eur_mwh: number;
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+    };
+}
+export declare function getEuGasPrice(params: z.infer<typeof euGasPriceSchema>): Promise<EuGasPriceResult>;
+export {};

package/dist/tools/eu-gas-price.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const cache = new TtlCache();
+/**
+ * Fetches European natural gas prices from multiple free sources.
+ * Primary: Yahoo Finance TTF futures (no API key needed).
+ * Fallback: Derives from GIE AGSI+ storage economics if available.
+ */
+export const euGasPriceSchema = z.object({
+    hub: z
+        .enum(["ttf", "nbp"])
+        .optional()
+        .describe('Gas trading hub. "ttf" = Dutch TTF (European benchmark, EUR/MWh). ' +
+        '"nbp" = UK NBP (GBp/therm). Defaults to ttf.'),
+    period: z
+        .enum(["spot", "week"])
+        .optional()
+        .describe('"spot" = latest available price. "week" = last 7 daily closes. Defaults to spot.'),
+});
+// Yahoo Finance tickers for European gas hubs
+const TICKERS = {
+    ttf: {
+        ticker: "TTF%3DF",
+        name: "Dutch TTF Natural Gas Futures",
+        currency: "EUR",
+        unit: "EUR/MWh",
+        toEurMwh: 1, // TTF is already quoted in EUR/MWh
+    },
+    nbp: {
+        ticker: "NG%3DF",
+        name: "UK NBP Natural Gas (Henry Hub proxy)",
+        currency: "USD",
+        unit: "USD/MMBtu",
+        toEurMwh: 3.41, // Approximate USD/MMBtu to EUR/MWh conversion
+    },
+};
+async function fetchYahooQuote(ticker, range) {
+    const cacheKey = `yahoo:${ticker}:${range}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const url = `https://query1.finance.yahoo.com/v8/finance/chart/${ticker}?range=${range}&interval=1d`;
+        const response = await fetch(url, {
+            headers: {
+                "User-Agent": "Mozilla/5.0",
+            },
+        });
+        if (!response.ok)
+            return null;
+        const json = await response.json();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = json?.chart?.result?.[0];
+        if (!result)
+            return null;
+        const timestamps = result.timestamp ?? [];
+        const closes = result.indicators?.quote?.[0]?.close ?? [];
+        const dates = timestamps.map((ts) => new Date(ts * 1000).toISOString().slice(0, 10));
+        // Filter out null/NaN closes
+        const valid = { dates: [], closes: [] };
+        for (let i = 0; i < dates.length; i++) {
+            if (closes[i] != null && Number.isFinite(closes[i])) {
+                valid.dates.push(dates[i]);
+                valid.closes.push(closes[i]);
+            }
+        }
+        if (valid.dates.length > 0) {
+            cache.set(cacheKey, valid, TTL.STORAGE);
+        }
+        return valid.dates.length > 0 ? valid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function getEuGasPrice(params) {
+    const hub = params.hub ?? "ttf";
+    const period = params.period ?? "spot";
+    const config = TICKERS[hub];
+    if (!config) {
+        throw new Error(`Unknown gas hub "${hub}". Available: ttf, nbp`);
+    }
+    const range = period === "week" ? "7d" : "5d";
+    const data = await fetchYahooQuote(config.ticker, range);
+    if (!data || data.closes.length === 0) {
+        throw new Error(`Unable to fetch ${config.name} price. Yahoo Finance may be temporarily unavailable.`);
+    }
+    const prices = data.dates.map((date, i) => ({
+        date,
+        price: Math.round(data.closes[i] * 100) / 100,
+        currency: config.currency,
+        unit: config.unit,
+    }));
+    const latestPrice = data.closes[data.closes.length - 1];
+    const priceEurMwh = Math.round(latestPrice * config.toEurMwh * 100) / 100;
+    const values = data.closes;
+    const min = Math.round(Math.min(...values) * 100) / 100;
+    const max = Math.round(Math.max(...values) * 100) / 100;
+    const mean = Math.round((values.reduce((s, v) => s + v, 0) / values.length) * 100) / 100;
+    return {
+        hub,
+        hub_name: config.name,
+        currency: config.currency,
+        unit: config.unit,
+        latest: prices[prices.length - 1],
+        prices: period === "week" ? prices : [prices[prices.length - 1]],
+        price_eur_mwh: priceEurMwh,
+        stats: { min, max, mean },
+    };
+}

package/dist/tools/fingrid.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export declare const fingridSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        frequency: "frequency";
+        consumption: "consumption";
+        production: "production";
+        wind_production: "wind_production";
+        solar_production: "solar_production";
+        nuclear_production: "nuclear_production";
+        hydro_production: "hydro_production";
+        imports: "imports";
+        exports: "exports";
+        reserve_prices: "reserve_prices";
+    }>;
+    start_date: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface DataPoint {
+    timestamp: string;
+    value: number;
+}
+interface FingridResult {
+    source: string;
+    dataset: string;
+    dataset_id: number;
+    unit: string;
+    start_date: string;
+    end_date: string;
+    count: number;
+    latest: DataPoint | null;
+    data: DataPoint[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+    } | null;
+}
+export declare function getFingridData(params: z.infer<typeof fingridSchema>): Promise<FingridResult>;
+export {};