@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/ree-esios.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const API_BASE = "https://api.esios.ree.es";
+const REE_PUBLIC = "https://www.ree.es/en/datos/apidatos";
+const cache = new TtlCache();
+/** ESIOS indicator IDs for key datasets */
+const INDICATORS = {
+    day_ahead_price: 600,
+    intraday_price: 612,
+    demand_forecast: 460,
+    demand_actual: 1293,
+    wind_forecast: 541,
+    wind_actual: 551,
+    solar_forecast: 542,
+    solar_actual: 552,
+    generation_mix: 1295,
+    interconnector_flows: 10210,
+};
+export const reeEsiosSchema = z.object({
+    dataset: z
+        .enum([
+        "day_ahead_price",
+        "demand",
+        "generation",
+        "wind_solar",
+        "interconnectors",
+    ])
+        .describe('"day_ahead_price" = Spanish day-ahead electricity prices (EUR/MWh). ' +
+        '"demand" = forecast and actual demand (MW). ' +
+        '"generation" = generation mix by technology. ' +
+        '"wind_solar" = wind and solar forecast vs actual (MW). ' +
+        '"interconnectors" = cross-border flows with France, Portugal, Morocco.'),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+async function getApiToken() {
+    try {
+        return await resolveApiKey("ESIOS_API_TOKEN");
+    }
+    catch {
+        throw new Error("ESIOS_API_TOKEN is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Request a free token by emailing consultasios@ree.es or via " +
+            REE_PUBLIC);
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function fetchEsios(indicatorId, startDate, endDate) {
+    const url = `${API_BASE}/indicators/${indicatorId}?` +
+        `start_date=${encodeURIComponent(startDate + "T00:00:00Z")}&` +
+        `end_date=${encodeURIComponent(endDate + "T23:59:59Z")}`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached.values;
+    const response = await fetch(url, {
+        headers: {
+            Accept: "application/json; application/vnd.esios-api-v1+json",
+            Authorization: `Token token="${await getApiToken()}"`,
+            "User-Agent": "luminus-mcp/0.2",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`ESIOS API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    const values = json?.indicator?.values ?? [];
+    cache.set(url, { values }, TTL.PRICES);
+    return values;
+}
+async function fetchPrices(date) {
+    const values = await fetchEsios(INDICATORS.day_ahead_price, date, date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const records = values.slice(0, 48).map((v) => ({
+        timestamp: v.datetime ?? v.date ?? "",
+        price_eur_mwh: Math.round((Number(v.value ?? 0)) * 100) / 100,
+    }));
+    const prices = records.map((r) => r.price_eur_mwh);
+    return {
+        dataset: "day_ahead_price",
+        source: "REE ESIOS (Red Eléctrica de España)",
+        date,
+        records,
+        stats: {
+            min: prices.length > 0 ? Math.round(Math.min(...prices) * 100) / 100 : 0,
+            max: prices.length > 0 ? Math.round(Math.max(...prices) * 100) / 100 : 0,
+            mean: prices.length > 0
+                ? Math.round((prices.reduce((s, v) => s + v, 0) / prices.length) * 100) / 100
+                : 0,
+        },
+    };
+}
+async function fetchDemand(date) {
+    const [forecastValues, actualValues] = await Promise.all([
+        fetchEsios(INDICATORS.demand_forecast, date, date),
+        fetchEsios(INDICATORS.demand_actual, date, date),
+    ]);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const actualMap = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    actualValues.forEach((v) => {
+        const ts = (v.datetime ?? "").slice(0, 16);
+        actualMap.set(ts, Number(v.value ?? 0));
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const records = forecastValues.slice(0, 48).map((v) => {
+        const ts = (v.datetime ?? "").slice(0, 16);
+        const forecast = Number(v.value ?? 0);
+        const actual = actualMap.get(ts) ?? 0;
+        return {
+            timestamp: v.datetime ?? "",
+            forecast_mw: Math.round(forecast),
+            actual_mw: Math.round(actual),
+            error_mw: Math.round(actual - forecast),
+        };
+    });
+    return {
+        dataset: "demand",
+        source: "REE ESIOS",
+        date,
+        records,
+    };
+}
+async function fetchGeneration(date) {
+    const values = await fetchEsios(INDICATORS.generation_mix, date, date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const records = values.slice(0, 50).map((v) => ({
+        timestamp: v.datetime ?? "",
+        technology: v.geo_name ?? v.name ?? "Unknown",
+        generation_mw: Math.round(Number(v.value ?? 0)),
+    }));
+    return {
+        dataset: "generation",
+        source: "REE ESIOS",
+        date,
+        records,
+    };
+}
+async function fetchWindSolar(date) {
+    const [windFc, windAct, solarFc, solarAct] = await Promise.all([
+        fetchEsios(INDICATORS.wind_forecast, date, date),
+        fetchEsios(INDICATORS.wind_actual, date, date),
+        fetchEsios(INDICATORS.solar_forecast, date, date),
+        fetchEsios(INDICATORS.solar_actual, date, date),
+    ]);
+    // Build a time-aligned merge
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const toMap = (arr) => {
+        const m = new Map();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        arr.forEach((v) => {
+            const ts = (v.datetime ?? "").slice(0, 16);
+            m.set(ts, Number(v.value ?? 0));
+        });
+        return m;
+    };
+    const windActMap = toMap(windAct);
+    const solarFcMap = toMap(solarFc);
+    const solarActMap = toMap(solarAct);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const records = windFc.slice(0, 48).map((v) => {
+        const ts = (v.datetime ?? "").slice(0, 16);
+        return {
+            timestamp: v.datetime ?? "",
+            wind_forecast_mw: Math.round(Number(v.value ?? 0)),
+            wind_actual_mw: Math.round(windActMap.get(ts) ?? 0),
+            solar_forecast_mw: Math.round(solarFcMap.get(ts) ?? 0),
+            solar_actual_mw: Math.round(solarActMap.get(ts) ?? 0),
+        };
+    });
+    return {
+        dataset: "wind_solar",
+        source: "REE ESIOS",
+        date,
+        records,
+    };
+}
+async function fetchInterconnectors(date) {
+    const values = await fetchEsios(INDICATORS.interconnector_flows, date, date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const records = values.slice(0, 30).map((v) => {
+        const flow = Number(v.value ?? 0);
+        return {
+            border: v.geo_name ?? v.name ?? "Unknown",
+            flow_mw: Math.round(flow),
+            direction: flow >= 0 ? "import" : "export",
+            timestamp: v.datetime ?? "",
+        };
+    });
+    const netImport = records.reduce((s, r) => s + r.flow_mw, 0);
+    return {
+        dataset: "interconnectors",
+        source: "REE ESIOS",
+        date,
+        records,
+        net_import_mw: netImport,
+    };
+}
+export async function getReeEsios(params) {
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    switch (params.dataset) {
+        case "day_ahead_price":
+            return fetchPrices(date);
+        case "demand":
+            return fetchDemand(date);
+        case "generation":
+            return fetchGeneration(date);
+        case "wind_solar":
+            return fetchWindSolar(date);
+        case "interconnectors":
+            return fetchInterconnectors(date);
+    }
+}

package/dist/tools/regelleistung.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const regelleistungSchema: z.ZodObject<{
+    product: z.ZodEnum<{
+        FCR: "FCR";
+        aFRR: "aFRR";
+        mFRR: "mFRR";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface TenderRecord {
+    product: string;
+    delivery_date: string;
+    direction: string;
+    procured_mw: number;
+    marginal_price_eur_mw: number;
+    average_price_eur_mw: number;
+    min_price_eur_mw: number;
+    max_price_eur_mw: number;
+}
+interface RegelleistungResult {
+    source: string;
+    product: string;
+    date: string;
+    description: string;
+    tenders: TenderRecord[];
+}
+export declare function getRegelleistung(params: z.infer<typeof regelleistungSchema>): Promise<RegelleistungResult>;
+export {};

package/dist/tools/regelleistung.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const API_BASE = "https://www.regelleistung.net/apps/datacenter/tenders";
+const cache = new TtlCache();
+const PRODUCTS = ["FCR", "aFRR", "mFRR"];
+export const regelleistungSchema = z.object({
+    product: z
+        .enum(PRODUCTS)
+        .describe('"FCR" = Frequency Containment Reserve (primary, ±200mHz, all EU). ' +
+        '"aFRR" = automatic Frequency Restoration Reserve (secondary, 5min). ' +
+        '"mFRR" = manual Frequency Restoration Reserve (tertiary, 15min).'),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+export async function getRegelleistung(params) {
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    const product = params.product;
+    const url = `${API_BASE}?productTypes=${product}&deliveryDate=${date}&format=json`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = await fetch(url, {
+        headers: { Accept: "application/json", "User-Agent": "luminus-mcp/0.2" },
+    });
+    if (!response.ok) {
+        // Regelleistung may not have a clean JSON API; fall back to description
+        const descriptions = {
+            FCR: "FCR (Frequency Containment Reserve): ±200mHz deadband, symmetric product, " +
+                "auctioned daily via the FCR Cooperation (DE, FR, NL, BE, AT, CH, DK, SI). " +
+                "Primary revenue stream for European BESS. Check regelleistung.net/apps/datacenter for latest results.",
+            aFRR: "aFRR (automatic Frequency Restoration Reserve): Activated within 5 minutes, " +
+                "energy + capacity pricing. DE-specific but harmonising across EU. " +
+                "Check regelleistung.net/apps/datacenter for latest results.",
+            mFRR: "mFRR (manual Frequency Restoration Reserve): Activated within 15 minutes, " +
+                "manual dispatch. Often used for larger imbalances. " +
+                "Check regelleistung.net/apps/datacenter for latest results.",
+        };
+        return {
+            source: "Regelleistung.net (Balancing Market Data Center)",
+            product,
+            date,
+            description: descriptions[product] ?? `${product} balancing reserve data. No tender results available from the API for this date.`,
+            tenders: [],
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const items = Array.isArray(json) ? json : json?.data ?? json?.tenders ?? [];
+    const tenders = items.slice(0, 30).map((t) => ({
+        product: t.productType ?? product,
+        delivery_date: t.deliveryDate ?? date,
+        direction: t.direction ?? "symmetric",
+        procured_mw: Math.round(Number(t.procuredCapacity ?? t.demandMw ?? 0)),
+        marginal_price_eur_mw: Math.round((Number(t.marginalPrice ?? 0)) * 100) / 100,
+        average_price_eur_mw: Math.round((Number(t.averagePrice ?? t.weightedAveragePrice ?? 0)) * 100) / 100,
+        min_price_eur_mw: Math.round((Number(t.minPrice ?? 0)) * 100) / 100,
+        max_price_eur_mw: Math.round((Number(t.maxPrice ?? 0)) * 100) / 100,
+    }));
+    const result = {
+        source: "Regelleistung.net (Balancing Market Data Center)",
+        product,
+        date,
+        description: `${product} tender results for ${date}. ${tenders.length} records.`,
+        tenders,
+    };
+    cache.set(url, result, TTL.ANCILLARY);
+    return result;
+}

package/dist/tools/remit-messages.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const remitMessagesSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface RemitMessage {
+    id: string;
+    plant: string;
+    fuel: string | null;
+    type: "planned" | "unplanned" | string;
+    availableMW: number | null;
+    unavailableMW: number | null;
+    start: string;
+    end: string;
+    reason: string | null;
+}
+export declare function getRemitMessages(params: z.infer<typeof remitMessagesSchema>): Promise<{
+    zone: string;
+    date: string;
+    messageCount: number;
+    messages: RemitMessage[];
+}>;
+export {};

package/dist/tools/remit-messages.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { queryEntsoe, formatEntsoeDate } 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";
+/** PSR type codes to human-readable fuel names */
+const PSR_TYPES = {
+    B01: "Biomass",
+    B02: "Lignite",
+    B03: "Coal-derived gas",
+    B04: "Gas",
+    B05: "Hard coal",
+    B06: "Oil",
+    B09: "Geothermal",
+    B10: "Hydro Pumped Storage",
+    B11: "Hydro Run-of-river",
+    B12: "Hydro Reservoir",
+    B14: "Nuclear",
+    B16: "Solar",
+    B18: "Wind Offshore",
+    B19: "Wind Onshore",
+};
+export const remitMessagesSchema = 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 getRemitMessages(params) {
+    const eic = resolveZone(params.zone);
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    const base = new Date(date + "T00:00:00Z");
+    const start = new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth(), base.getUTCDate()));
+    const end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
+    let data;
+    try {
+        data = await queryEntsoe({
+            documentType: "A80",
+            processType: "A26",
+            biddingZone_Domain: eic,
+            periodStart: formatEntsoeDate(start),
+            periodEnd: formatEntsoeDate(end),
+        }, TTL.OUTAGES);
+    }
+    catch {
+        // API error or no data = empty result, not a thrown error
+        return { zone: params.zone.toUpperCase(), date, messageCount: 0, messages: [] };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const doc = data.UnavailabilityMarketDocument ??
+        data.Unavailability_MarketDocument;
+    if (!doc) {
+        return { zone: params.zone.toUpperCase(), date, messageCount: 0, messages: [] };
+    }
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const messages = [];
+    for (const ts of timeSeries) {
+        const resource = ts.production_RegisteredResource ?? ts.Asset_RegisteredResource ?? {};
+        const plant = resource.name ?? resource.mRID ?? "Unknown";
+        const psrCode = resource.pSRType?.psrType ?? null;
+        const fuel = psrCode ? (PSR_TYPES[psrCode] ?? psrCode) : null;
+        const nominalMw = resource.pSRType?.powerSystemResources?.nominalP
+            ? Number(resource.pSRType.powerSystemResources.nominalP)
+            : null;
+        const businessType = ts.businessType ?? "";
+        const outageType = businessType === "A53" ? "planned"
+            : businessType === "A54" ? "unplanned"
+                : businessType;
+        const startDate = ts.start_DateAndOrTime?.date ?? ts.start_DateAndOrTime ?? "";
+        const endDate = ts.end_DateAndOrTime?.date ?? ts.end_DateAndOrTime ?? "";
+        const reason = ts.Reason?.text ?? null;
+        const id = ts.mRID ?? "";
+        const availPeriods = ensureArray(ts.Available_Period);
+        let availableMw = null;
+        for (const period of availPeriods) {
+            const points = ensureArray(period.Point);
+            if (points.length > 0) {
+                availableMw = Number(points[0].quantity ?? 0);
+                break;
+            }
+        }
+        const unavailableMw = nominalMw != null && availableMw != null
+            ? Math.round(nominalMw - availableMw)
+            : null;
+        messages.push({
+            id,
+            plant,
+            fuel,
+            type: outageType,
+            availableMW: availableMw != null ? Math.round(availableMw) : null,
+            unavailableMW: unavailableMw,
+            start: startDate,
+            end: endDate,
+            reason,
+        });
+    }
+    // Sort by unavailableMW descending, nulls last
+    messages.sort((a, b) => (b.unavailableMW ?? 0) - (a.unavailableMW ?? 0));
+    // Limit to first 20
+    const limited = messages.slice(0, 20);
+    return {
+        zone: params.zone.toUpperCase(),
+        date,
+        messageCount: limited.length,
+        messages: limited,
+    };
+}

package/dist/tools/renewable-forecast.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const renewableForecastSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface ForecastPoint {
+    hour: number;
+    mw: number;
+}
+interface RenewableForecastEntry {
+    source: string;
+    psr_code: string;
+    forecast: ForecastPoint[];
+    peak_mw: number;
+    total_mwh: number;
+}
+export declare function getRenewableForecast(params: z.infer<typeof renewableForecastSchema>): Promise<{
+    zone: string;
+    date: string;
+    forecasts: RenewableForecastEntry[];
+    total_peak_mw: number;
+}>;
+export {};

package/dist/tools/renewable-forecast.js

@@ -0,0 +1,75 @@
+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";
+/** PSR type codes for renewable sources */
+const RENEWABLE_PSR = {
+    B16: "Solar",
+    B18: "Wind Offshore",
+    B19: "Wind Onshore",
+};
+export const renewableForecastSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Country/zone code. Examples: DE, FR, ES. Available: ${AVAILABLE_ZONES}`),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+export async function getRenewableForecast(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: "A69",
+        processType: "A01",
+        in_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.FORECAST);
+    const doc = data.GL_MarketDocument;
+    if (!doc)
+        throw new Error("No renewable forecast data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const forecastMap = new Map();
+    for (const ts of timeSeries) {
+        const psrCode = ts.MktPSRType?.psrType ?? "unknown";
+        const source = RENEWABLE_PSR[psrCode] ?? psrCode;
+        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 ?? 0);
+                if (!forecastMap.has(source))
+                    forecastMap.set(source, []);
+                forecastMap.get(source).push({ hour: position - 1, mw });
+            }
+        }
+    }
+    const forecasts = [];
+    for (const [source, points] of forecastMap) {
+        points.sort((a, b) => a.hour - b.hour);
+        const values = points.map((p) => p.mw);
+        const peak_mw = values.length > 0 ? Math.max(...values) : 0;
+        const total_mwh = values.reduce((s, v) => s + v, 0);
+        const psrEntry = Object.entries(RENEWABLE_PSR).find(([, v]) => v === source);
+        forecasts.push({
+            source,
+            psr_code: psrEntry ? psrEntry[0] : "unknown",
+            forecast: points,
+            peak_mw,
+            total_mwh,
+        });
+    }
+    forecasts.sort((a, b) => b.peak_mw - a.peak_mw);
+    const total_peak_mw = forecasts.reduce((s, f) => s + f.peak_mw, 0);
+    return {
+        zone: params.zone.toUpperCase(),
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        forecasts,
+        total_peak_mw,
+    };
+}

package/dist/tools/rte-france.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const rteFranceSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        generation: "generation";
+        outages: "outages";
+        consumption: "consumption";
+        exchanges: "exchanges";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface GenerationRecord {
+    timestamp: string;
+    nuclear_mw: number;
+    wind_mw: number;
+    solar_mw: number;
+    hydro_mw: number;
+    gas_mw: number;
+    coal_mw: number;
+    bioenergy_mw: number;
+    total_mw: number;
+}
+interface FranceGenerationResult {
+    dataset: "generation";
+    source: string;
+    date: string;
+    records: GenerationRecord[];
+    latest: GenerationRecord | null;
+}
+interface ConsumptionRecord {
+    timestamp: string;
+    consumption_mw: number;
+    forecast_mw: number;
+}
+interface FranceConsumptionResult {
+    dataset: "consumption";
+    source: string;
+    date: string;
+    records: ConsumptionRecord[];
+}
+interface ExchangeRecord {
+    timestamp: string;
+    gb_mw: number;
+    spain_mw: number;
+    italy_mw: number;
+    switzerland_mw: number;
+    germany_belgium_mw: number;
+    net_mw: number;
+}
+interface FranceExchangesResult {
+    dataset: "exchanges";
+    source: string;
+    date: string;
+    records: ExchangeRecord[];
+}
+interface OutageRecord {
+    unit_name: string;
+    fuel_type: string;
+    unavailable_mw: number;
+    available_mw: number;
+    start_date: string;
+    end_date: string;
+    reason: string;
+}
+interface FranceOutagesResult {
+    dataset: "outages";
+    source: string;
+    description: string;
+    records: OutageRecord[];
+}
+type RteFranceResult = FranceGenerationResult | FranceConsumptionResult | FranceExchangesResult | FranceOutagesResult;
+export declare function getRteFrance(params: z.infer<typeof rteFranceSchema>): Promise<RteFranceResult>;
+export {};