@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/auctions.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const auctionSchema: z.ZodObject<{
+    date: z.ZodString;
+    corridor: z.ZodString;
+}, z.core.$strip>;
+interface AuctionResult {
+    corridor: string;
+    date: string;
+    allocated_capacity_mw: number | null;
+    auction_price_eur_mw: number | null;
+    offered_capacity_mw: number | null;
+    requested_capacity_mw: number | null;
+}
+export declare function getAuctionResults(params: z.infer<typeof auctionSchema>): Promise<AuctionResult>;
+export {};

package/dist/tools/auctions.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const BASE_URL = "https://publicationtool.jao.eu/core/api/data";
+const cache = new TtlCache();
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+const CORRIDORS = [
+    "DE-FR", "FR-DE", "DE-NL", "NL-DE", "DE-BE", "BE-DE",
+    "DE-AT", "AT-DE", "DE-PL", "PL-DE", "DE-CZ", "CZ-DE",
+    "DE-DK1", "DK1-DE", "FR-BE", "BE-FR", "FR-ES", "ES-FR",
+    "NL-BE", "BE-NL", "AT-CZ", "CZ-AT", "AT-HU", "HU-AT",
+    "AT-SI", "SI-AT", "PL-CZ", "CZ-PL", "PL-SK", "SK-PL",
+    "HU-SK", "SK-HU", "HU-RO", "RO-HU", "HR-SI", "SI-HR",
+    "HR-HU", "HU-HR",
+];
+export const auctionSchema = z.object({
+    date: z
+        .string()
+        .describe("Auction date in YYYY-MM-DD format."),
+    corridor: z
+        .string()
+        .describe(`Border corridor (e.g. DE-FR, FR-DE, NL-BE). Available: ${CORRIDORS.slice(0, 10).join(", ")}...`),
+});
+async function fetchWithRetry(url, retries = MAX_RETRIES) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
+        try {
+            const response = await fetch(url, {
+                headers: { Accept: "application/json" },
+            });
+            if (response.ok)
+                return response;
+            if (attempt < retries && response.status >= 500) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * attempt));
+                continue;
+            }
+            const body = await response.text();
+            throw new Error(`JAO API returned ${response.status}: ${body.slice(0, 300)}`);
+        }
+        catch (err) {
+            if (attempt >= retries)
+                throw err;
+            await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * attempt));
+        }
+    }
+    throw new Error("JAO API: max retries exceeded");
+}
+export async function getAuctionResults(params) {
+    const corridor = params.corridor.toUpperCase();
+    const cacheKey = `jao:${corridor}:${params.date}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    // JAO API requires FromUtc and ToUtc as ISO datetime range
+    const fromUtc = `${params.date}T00:00:00.000Z`;
+    const toUtc = `${params.date}T23:59:59.999Z`;
+    const url = `${BASE_URL}/finalComputation?FromUtc=${fromUtc}&ToUtc=${toUtc}&corridor=${corridor}`;
+    const response = await fetchWithRetry(url);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    // JAO finalComputation endpoint now returns CNEC flow-based data (not auction allocations).
+    // Extract cross-border capacity results for the requested corridor.
+    const entries = Array.isArray(json) ? json : json.data ? (Array.isArray(json.data) ? json.data : [json.data]) : [json];
+    if (entries.length === 0) {
+        throw new Error(`No auction data for corridor ${corridor} on ${params.date}.`);
+    }
+    // Filter entries relevant to this corridor direction
+    const [hubFrom, hubTo] = corridor.split("-");
+    const relevant = entries.filter((e) => e.hubFrom === hubFrom && e.hubTo === hubTo);
+    // Aggregate: sum RAM (Remaining Available Margin) across CNECs as a capacity proxy
+    let totalRamMw = 0;
+    let count = 0;
+    for (const e of relevant) {
+        const ram = Number(e.ram ?? 0);
+        if (ram > 0) {
+            totalRamMw += ram;
+            count++;
+        }
+    }
+    const result = {
+        corridor,
+        date: params.date,
+        allocated_capacity_mw: count > 0 ? Math.round(totalRamMw / count) : null,
+        auction_price_eur_mw: null, // No longer in this endpoint
+        offered_capacity_mw: count > 0 ? Math.round(totalRamMw / count) : null,
+        requested_capacity_mw: null,
+    };
+    cache.set(cacheKey, result, TTL.AUCTION);
+    return result;
+}

package/dist/tools/balancing-actions.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const balancingActionsSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface BalancingAction {
+    direction: "up" | "down";
+    volume_mw: number;
+    period: number;
+}
+interface BalancingActionsResult {
+    zone: string;
+    date: string;
+    actions: BalancingAction[];
+    summary: {
+        total_up_mw: number;
+        total_down_mw: number;
+        net_mw: number;
+    };
+}
+export declare function getBalancingActions(params: z.infer<typeof balancingActionsSchema>): Promise<BalancingActionsResult>;
+export {};

package/dist/tools/balancing-actions.js

@@ -0,0 +1,151 @@
+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 { TtlCache, TTL } from "../lib/cache.js";
+const ELEXON_API = "https://data.elexon.co.uk/bmrs/api/v1";
+const cache = new TtlCache();
+export const balancingActionsSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Bidding zone code. Examples: DE, FR, GB. Available: ${AVAILABLE_ZONES}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function fetchElexon(path) {
+    const url = `${ELEXON_API}${path}`;
+    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(`Elexon BMRS API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(url, json, TTL.BALANCING);
+    return json;
+}
+async function getGbBalancingActions(date) {
+    const data = await fetchElexon(`/datasets/BOD?settlementDate=${date}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    if (rows.length === 0) {
+        throw new Error("No GB balancing action data available from Elexon BMRS.");
+    }
+    // Aggregate volumes per settlement period and direction
+    const periodMap = new Map();
+    for (const row of rows) {
+        const sp = Number(row.settlementPeriod ?? 0);
+        const level = Number(row.bidOfferPairNumber ?? 0);
+        const volume = Number(row.bidOfferLevelTo ?? 0) - Number(row.bidOfferLevelFrom ?? 0);
+        if (!periodMap.has(sp)) {
+            periodMap.set(sp, { up: 0, down: 0 });
+        }
+        const entry = periodMap.get(sp);
+        if (level > 0 && volume > 0) {
+            entry.up += volume;
+        }
+        else if (level < 0 && volume < 0) {
+            entry.down += Math.abs(volume);
+        }
+    }
+    const actions = [];
+    for (const [period, volumes] of periodMap) {
+        if (volumes.up > 0) {
+            actions.push({
+                direction: "up",
+                volume_mw: Math.round(volumes.up),
+                period,
+            });
+        }
+        if (volumes.down > 0) {
+            actions.push({
+                direction: "down",
+                volume_mw: Math.round(volumes.down),
+                period,
+            });
+        }
+    }
+    actions.sort((a, b) => a.period - b.period);
+    const totalUp = actions
+        .filter((a) => a.direction === "up")
+        .reduce((sum, a) => sum + a.volume_mw, 0);
+    const totalDown = actions
+        .filter((a) => a.direction === "down")
+        .reduce((sum, a) => sum + a.volume_mw, 0);
+    return {
+        zone: "GB",
+        date,
+        actions,
+        summary: {
+            total_up_mw: totalUp,
+            total_down_mw: totalDown,
+            net_mw: totalUp - totalDown,
+        },
+    };
+}
+async function getEntsoeBalancingActions(zone, date) {
+    const eic = resolveZone(zone);
+    const { periodStart, periodEnd } = dayRange(date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = await queryEntsoe({
+        documentType: "A88",
+        processType: "A16",
+        controlArea_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.BALANCING);
+    const doc = data.GL_MarketDocument ?? data.Imbalance_MarketDocument ?? data.Publication_MarketDocument;
+    if (!doc)
+        throw new Error("No balancing action data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const actions = [];
+    for (const ts of timeSeries) {
+        // flowDirection.direction: A01 = up (increase generation), A02 = down (decrease generation)
+        const flowDir = ts["flowDirection.direction"] ?? ts.flowDirection ?? "";
+        const direction = flowDir === "A02" ? "down" : "up";
+        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 volume = Number(point.quantity ?? 0);
+                if (volume > 0) {
+                    actions.push({
+                        direction,
+                        volume_mw: Math.round(volume),
+                        period: position,
+                    });
+                }
+            }
+        }
+    }
+    actions.sort((a, b) => a.period - b.period);
+    const totalUp = actions
+        .filter((a) => a.direction === "up")
+        .reduce((sum, a) => sum + a.volume_mw, 0);
+    const totalDown = actions
+        .filter((a) => a.direction === "down")
+        .reduce((sum, a) => sum + a.volume_mw, 0);
+    return {
+        zone: zone.toUpperCase(),
+        date: date ?? new Date().toISOString().slice(0, 10),
+        actions,
+        summary: {
+            total_up_mw: totalUp,
+            total_down_mw: totalDown,
+            net_mw: totalUp - totalDown,
+        },
+    };
+}
+export async function getBalancingActions(params) {
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    if (params.zone.toUpperCase() === "GB") {
+        return getGbBalancingActions(date);
+    }
+    return getEntsoeBalancingActions(params.zone, params.date);
+}

package/dist/tools/balancing.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const balancingSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface ImbalancePricePoint {
+    period: number;
+    price_eur_mwh: number;
+}
+export declare function getBalancingPrices(params: z.infer<typeof balancingSchema>): Promise<{
+    zone: string;
+    date: string;
+    currency: string;
+    prices: ImbalancePricePoint[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+    };
+}>;
+export {};

package/dist/tools/balancing.js

@@ -0,0 +1,56 @@
+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 balancingSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Bidding zone code. Examples: DE, FR, GB. Available: ${AVAILABLE_ZONES}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+export async function getBalancingPrices(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: "A85",
+        processType: "A16",
+        controlArea_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.BALANCING);
+    const doc = data.Imbalance_MarketDocument ?? data.GL_MarketDocument ?? data.Publication_MarketDocument;
+    if (!doc)
+        throw new Error("No balancing price data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const prices = [];
+    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 price = Number(point["imbalance_Price.amount"] ?? point["price.amount"] ?? point.quantity ?? 0);
+                prices.push({ period: position, price_eur_mwh: price });
+            }
+        }
+    }
+    prices.sort((a, b) => a.period - b.period);
+    const values = prices.map((p) => p.price_eur_mwh);
+    const min = values.length > 0 ? Math.min(...values) : 0;
+    const max = values.length > 0 ? Math.max(...values) : 0;
+    const mean = values.length > 0
+        ? Math.round((values.reduce((s, v) => s + v, 0) / values.length) * 100) / 100
+        : 0;
+    return {
+        zone: params.zone.toUpperCase(),
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        currency: "EUR",
+        prices,
+        stats: { min, max, mean },
+    };
+}

package/dist/tools/carbon.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const carbonSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface CarbonBreakdown {
+    fuel_type: string;
+    mw: number;
+    emission_factor_gco2_kwh: number;
+    contribution_gco2_kwh: number;
+}
+export declare function getCarbonIntensity(params: z.infer<typeof carbonSchema>): Promise<{
+    zone: string;
+    date: string;
+    carbon_intensity_gco2_kwh: number;
+    total_mw: number;
+    breakdown: CarbonBreakdown[];
+    renewable_pct: number;
+    fossil_pct: number;
+}>;
+export {};

package/dist/tools/carbon.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { getGenerationMix, generationSchema } from "./generation.js";
+export const carbonSchema = z.object({
+    zone: generationSchema.shape.zone,
+    date: generationSchema.shape.date,
+});
+/** Emission factors in gCO2/kWh by PSR code */
+const EMISSION_FACTORS = {
+    B01: 50, // Biomass
+    B02: 900, // Lignite
+    B03: 400, // Coal-derived gas
+    B04: 400, // Gas
+    B05: 900, // Hard coal
+    B06: 650, // Oil
+    B07: 650, // Oil shale
+    B08: 900, // Peat
+    B09: 0, // Geothermal
+    B10: 0, // Hydro Pumped Storage (assumed zero at point of generation)
+    B11: 0, // Hydro Run-of-river
+    B12: 0, // Hydro Reservoir
+    B13: 0, // Marine
+    B14: 0, // Nuclear
+    B15: 0, // Other renewable
+    B16: 0, // Solar
+    B17: 100, // Waste
+    B18: 0, // Wind Offshore
+    B19: 0, // Wind Onshore
+    B20: 300, // Other (conservative estimate)
+};
+export async function getCarbonIntensity(params) {
+    const genData = await getGenerationMix(params);
+    const breakdown = [];
+    let totalEmissions = 0;
+    for (const gen of genData.generation) {
+        const factor = EMISSION_FACTORS[gen.psr_code] ?? 300;
+        const contribution = (gen.mw / genData.total_mw) * factor;
+        totalEmissions += contribution;
+        breakdown.push({
+            fuel_type: gen.fuel_type,
+            mw: gen.mw,
+            emission_factor_gco2_kwh: factor,
+            contribution_gco2_kwh: Math.round(contribution * 100) / 100,
+        });
+    }
+    const renewableCodes = new Set([
+        "B01", "B09", "B10", "B11", "B12", "B13", "B15", "B16", "B18", "B19",
+    ]);
+    const fossilCodes = new Set(["B02", "B03", "B04", "B05", "B06", "B07", "B08"]);
+    const renewableMw = genData.generation
+        .filter((g) => renewableCodes.has(g.psr_code))
+        .reduce((s, g) => s + g.mw, 0);
+    const fossilMw = genData.generation
+        .filter((g) => fossilCodes.has(g.psr_code))
+        .reduce((s, g) => s + g.mw, 0);
+    return {
+        zone: genData.zone,
+        date: genData.date,
+        carbon_intensity_gco2_kwh: Math.round(totalEmissions * 100) / 100,
+        total_mw: genData.total_mw,
+        breakdown,
+        renewable_pct: genData.total_mw > 0
+            ? Math.round((renewableMw / genData.total_mw) * 10000) / 100
+            : 0,
+        fossil_pct: genData.total_mw > 0
+            ? Math.round((fossilMw / genData.total_mw) * 10000) / 100
+            : 0,
+    };
+}

package/dist/tools/commodity-prices.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const commodityPricesSchema: z.ZodObject<{
+    commodity: z.ZodEnum<{
+        ttf: "ttf";
+        carbon: "carbon";
+        brent: "brent";
+        all: "all";
+    }>;
+}, z.core.$strip>;
+interface CommodityEntry {
+    name: string;
+    ticker: string;
+    price: number;
+    currency: string;
+    unit: string;
+    change_5d_pct: number;
+    prices_5d: {
+        date: string;
+        price: number;
+    }[];
+}
+interface CommodityPricesResult {
+    commodities: CommodityEntry[];
+}
+export declare function getCommodityPrices(params: z.infer<typeof commodityPricesSchema>): Promise<CommodityPricesResult>;
+export {};

package/dist/tools/commodity-prices.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const cache = new TtlCache();
+export const commodityPricesSchema = z.object({
+    commodity: z.enum(["carbon", "brent", "ttf", "all"]).describe('"carbon" = EU ETS carbon allowance (EUR/tCO2). "brent" = Brent crude (USD/bbl). "ttf" = Dutch TTF gas (EUR/MWh). "all" = all three.'),
+});
+const COMMODITIES = {
+    carbon: {
+        ticker: "CO2.L",
+        name: "EU Carbon (EUA)",
+        currency: "EUR",
+        unit: "EUR/tCO2",
+    },
+    brent: {
+        ticker: "BZ%3DF",
+        name: "Brent Crude",
+        currency: "USD",
+        unit: "USD/bbl",
+    },
+    ttf: {
+        ticker: "TTF%3DF",
+        name: "TTF Natural Gas",
+        currency: "EUR",
+        unit: "EUR/MWh",
+    },
+};
+async function fetchYahoo5d(ticker) {
+    const cacheKey = `commodity:${ticker}:5d`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const url = `https://query1.finance.yahoo.com/v8/finance/chart/${ticker}?range=5d&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 valid = { dates: [], closes: [] };
+        for (let i = 0; i < timestamps.length; i++) {
+            if (closes[i] != null && Number.isFinite(closes[i])) {
+                valid.dates.push(new Date(timestamps[i] * 1000).toISOString().slice(0, 10));
+                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;
+    }
+}
+function buildEntry(key, data) {
+    const config = COMMODITIES[key];
+    const latestPrice = data.closes[data.closes.length - 1];
+    const firstPrice = data.closes[0];
+    const change5dPct = firstPrice > 0
+        ? Math.round(((latestPrice - firstPrice) / firstPrice) * 10000) / 100
+        : 0;
+    const prices5d = data.dates.map((date, i) => ({
+        date,
+        price: Math.round(data.closes[i] * 100) / 100,
+    }));
+    return {
+        name: config.name,
+        ticker: config.ticker,
+        price: Math.round(latestPrice * 100) / 100,
+        currency: config.currency,
+        unit: config.unit,
+        change_5d_pct: change5dPct,
+        prices_5d: prices5d,
+    };
+}
+export async function getCommodityPrices(params) {
+    const keys = params.commodity === "all"
+        ? Object.keys(COMMODITIES)
+        : [params.commodity];
+    const results = await Promise.all(keys.map(async (key) => {
+        const config = COMMODITIES[key];
+        const data = await fetchYahoo5d(config.ticker);
+        if (!data || data.closes.length === 0) {
+            return null;
+        }
+        return buildEntry(key, data);
+    }));
+    const commodities = results.filter((r) => r !== null);
+    if (commodities.length === 0) {
+        throw new Error("Unable to fetch commodity prices. Yahoo Finance may be temporarily unavailable.");
+    }
+    return { commodities };
+}

package/dist/tools/compare-sites.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const compareSitesSchema: z.ZodObject<{
+    sites: z.ZodArray<z.ZodObject<{
+        lat: z.ZodNumber;
+        lon: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    country: z.ZodString;
+    radius_km: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Verdict = "pass" | "warn" | "fail";
+interface RankedSite {
+    rank: number;
+    label: string;
+    lat: number;
+    lon: number;
+    verdict: Verdict;
+    flag_count: number;
+    solar_kwh_m2: number | null;
+    slope_deg: number | null;
+    nearest_grid_km: number | null;
+    constraint_count: number;
+    score: number;
+    reasoning: string;
+    data_gaps: string[];
+}
+interface FailedSite {
+    lat: number;
+    lon: number;
+    label: string;
+    error: string;
+}
+interface CompareSitesResult {
+    site_count: number;
+    rankings: RankedSite[];
+    failed_sites: FailedSite[];
+    heuristics_used: string[];
+    disclaimer: string;
+}
+export declare function compareSites(params: z.infer<typeof compareSitesSchema>): Promise<CompareSitesResult>;
+export {};