@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/land-cover.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { queryCorineAtPoint, CORINE_COVERED_COUNTRIES } from "../lib/corine.js";
+import { GIS_SOURCES } from "../lib/gis-sources.js";
+const cache = new TtlCache();
+export const landCoverSchema = 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. Required to select the correct data source. " +
+        "CORINE 2018 covers EU27 + EEA/EFTA countries. Great Britain (GB) is not covered " +
+        "(UK withdrew from CORINE after 2012); use get_agricultural_land for GB land-use context instead."),
+});
+export async function getLandCover(params) {
+    const { lat, lon } = params;
+    const country = params.country.toUpperCase();
+    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.");
+    }
+    if (country === "GB") {
+        return {
+            lat,
+            lon,
+            country: "GB",
+            land_cover: null,
+            coverage_note: "Great Britain is not covered by CORINE Land Cover 2018. The UK withdrew from the " +
+                "programme after CLC 2012. Use get_agricultural_land for agricultural land classification " +
+                "in England, or get_land_constraints for protected-area context.",
+            source_metadata: GIS_SOURCES["corine-land-cover"],
+        };
+    }
+    if (!CORINE_COVERED_COUNTRIES.has(country)) {
+        throw new Error(`Country "${params.country}" is not supported by CORINE Land Cover 2018. ` +
+            "Supported: EU27 member states plus EEA/EFTA countries (IS, LI, NO, TR, AL, BA, ME, MK, RS, XK).");
+    }
+    const cacheKey = `land-cover:${lat}:${lon}:${country}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const landCover = await queryCorineAtPoint(lat, lon);
+        const result = {
+            lat,
+            lon,
+            country,
+            land_cover: landCover,
+            coverage_note: landCover === null
+                ? "No CORINE polygon found at this point. The location may be offshore, at a coverage boundary, " +
+                    "or below the 25 ha minimum mapping unit."
+                : null,
+            source_metadata: GIS_SOURCES["corine-land-cover"],
+        };
+        cache.set(cacheKey, result, TTL.STATIC_DATA);
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`CORINE Land Cover query failed: ${message}`);
+    }
+}

package/dist/tools/lng-terminals.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const lngTerminalsSchema: z.ZodObject<{
+    country: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface TerminalEntry {
+    name: string;
+    lng_inventory_mcm: number;
+    send_out_gwh: number;
+    capacity_mcm: number;
+    dtrs: number | null;
+    status: string;
+}
+interface LngData {
+    country: string;
+    date: string;
+    terminals: TerminalEntry[];
+    total_inventory_mcm: number;
+    total_send_out_gwh: number;
+}
+export declare function getLngTerminals(params: z.infer<typeof lngTerminalsSchema>): Promise<LngData>;
+export {};

package/dist/tools/lng-terminals.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const BASE_URL = "https://alsi.gie.eu/api";
+const cache = new TtlCache();
+const ALSI_COUNTRIES = [
+    "EU", "BE", "ES", "FR", "GB", "GR", "HR", "IT", "LT", "MT", "NL", "PL", "PT",
+];
+export const lngTerminalsSchema = z.object({
+    country: z
+        .string()
+        .optional()
+        .describe(`Country code for LNG terminal data. Available: ${ALSI_COUNTRIES.join(", ")}. Defaults to EU aggregate.`),
+    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://alsi.gie.eu/ (same key as AGSI+).");
+    }
+}
+function validateCountry(code) {
+    const upper = code.toUpperCase();
+    if (!ALSI_COUNTRIES.includes(upper)) {
+        throw new Error(`Unknown country "${code}". Available: ${ALSI_COUNTRIES.join(", ")}`);
+    }
+    return upper;
+}
+export async function getLngTerminals(params) {
+    const country = validateCountry(params.country ?? "EU");
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    const cacheKey = `alsi:${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(`ALSI API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    // 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 LNG terminal data for ${country} on ${date}.`);
+    }
+    const terminals = entries.map((e) => ({
+        name: e.name ?? e.facility ?? "Unknown",
+        lng_inventory_mcm: Number(e.lngInventory ?? 0),
+        send_out_gwh: Number(e.sendOut ?? 0),
+        capacity_mcm: Number(e.dtsp ?? 0),
+        dtrs: e.dtrs != null ? Number(e.dtrs) : null,
+        status: e.status ?? "unknown",
+    }));
+    const totalInventory = terminals.reduce((s, t) => s + t.lng_inventory_mcm, 0);
+    const totalSendOut = terminals.reduce((s, t) => s + t.send_out_gwh, 0);
+    const result = {
+        country,
+        date: entries[0]?.gasDayStart ?? date,
+        terminals,
+        total_inventory_mcm: totalInventory,
+        total_send_out_gwh: totalSendOut,
+    };
+    cache.set(cacheKey, result, TTL.STORAGE);
+    return result;
+}

package/dist/tools/net-positions.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const netPositionsSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface BorderFlow {
+    neighbour: string;
+    import_mw: number;
+    export_mw: number;
+    net_mw: number;
+}
+export declare function getNetPositions(params: z.infer<typeof netPositionsSchema>): Promise<{
+    zone: string;
+    date: string;
+    net_position_mw: number;
+    status: string;
+    borders: BorderFlow[];
+}>;
+export {};

package/dist/tools/net-positions.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { queryEntsoe, dayRange } from "../lib/entsoe-client.js";
+import { resolveZone, AVAILABLE_ZONES, ZONE_NEIGHBOURS } from "../lib/zone-codes.js";
+import { ensureArray } from "../lib/xml-parser.js";
+import { TTL } from "../lib/cache.js";
+export const netPositionsSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Country/zone code. Available: ${AVAILABLE_ZONES}. ` +
+        "Net position = total imports minus total exports across all borders."),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+async function queryFlow(fromEic, toEic, periodStart, periodEnd) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const data = await queryEntsoe({ documentType: "A11", in_Domain: toEic, out_Domain: fromEic, periodStart, periodEnd }, TTL.OUTAGES);
+        const doc = data.GL_MarketDocument;
+        if (!doc)
+            return 0;
+        const timeSeries = ensureArray(doc.TimeSeries);
+        let total = 0;
+        let count = 0;
+        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) {
+                    total += Number(point.quantity ?? 0);
+                    count++;
+                }
+            }
+        }
+        return count > 0 ? Math.round(total / count) : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function getNetPositions(params) {
+    const zoneUpper = params.zone.toUpperCase();
+    const neighbours = ZONE_NEIGHBOURS[zoneUpper];
+    if (!neighbours) {
+        throw new Error(`No neighbour mapping for "${zoneUpper}". Available: ${Object.keys(ZONE_NEIGHBOURS).join(", ")}`);
+    }
+    const zoneEic = resolveZone(zoneUpper);
+    const { periodStart, periodEnd } = dayRange(params.date);
+    // Query import and export flows for each neighbour in parallel
+    const borderPromises = neighbours.map(async (neighbour) => {
+        const neighbourEic = resolveZone(neighbour);
+        const [importMw, exportMw] = await Promise.all([
+            queryFlow(neighbourEic, zoneEic, periodStart, periodEnd),
+            queryFlow(zoneEic, neighbourEic, periodStart, periodEnd),
+        ]);
+        return {
+            neighbour,
+            import_mw: importMw,
+            export_mw: exportMw,
+            net_mw: importMw - exportMw,
+        };
+    });
+    const borders = await Promise.all(borderPromises);
+    const netPosition = borders.reduce((sum, b) => sum + b.net_mw, 0);
+    const status = netPosition > 0 ? "net importer" : netPosition < 0 ? "net exporter" : "balanced";
+    return {
+        zone: zoneUpper,
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        net_position_mw: netPosition,
+        status,
+        borders: borders.filter((b) => b.import_mw !== 0 || b.export_mw !== 0),
+    };
+}

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const nordpoolSchema: z.ZodObject<{
+    areas: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+    currency: z.ZodOptional<z.ZodEnum<{
+        EUR: "EUR";
+        NOK: "NOK";
+        SEK: "SEK";
+        DKK: "DKK";
+    }>>;
+}, z.core.$strip>;
+interface AreaPriceData {
+    prices: {
+        timestamp: string;
+        price: number;
+    }[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+    };
+}
+interface NordpoolResult {
+    date: string;
+    currency: string;
+    areas: Record<string, AreaPriceData>;
+}
+export declare function getNordpoolPrices(params: z.infer<typeof nordpoolSchema>): Promise<NordpoolResult>;
+export {};

package/dist/tools/nordpool-prices.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const cache = new TtlCache();
+const VALID_AREAS = new Set([
+    "SE1", "SE2", "SE3", "SE4",
+    "NO1", "NO2", "NO3", "NO4", "NO5",
+    "DK1", "DK2",
+    "FI",
+]);
+export const nordpoolSchema = z.object({
+    areas: z.string().describe('Comma-separated delivery areas. Available: SE1,SE2,SE3,SE4,NO1,NO2,NO3,NO4,NO5,DK1,DK2,FI. Example: "SE3,NO1,DK1"'),
+    date: z.string().optional().describe("Date YYYY-MM-DD. Defaults to today."),
+    currency: z
+        .enum(["EUR", "NOK", "SEK", "DKK"])
+        .optional()
+        .describe("Price currency. Defaults to EUR."),
+});
+function todayDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+export async function getNordpoolPrices(params) {
+    const date = params.date ?? todayDate();
+    const currency = params.currency ?? "EUR";
+    const requestedAreas = params.areas
+        .split(",")
+        .map((a) => a.trim().toUpperCase())
+        .filter((a) => a.length > 0);
+    const invalidAreas = requestedAreas.filter((a) => !VALID_AREAS.has(a));
+    if (invalidAreas.length > 0) {
+        throw new Error(`Invalid delivery areas: ${invalidAreas.join(", ")}. Available: ${[...VALID_AREAS].join(", ")}`);
+    }
+    if (requestedAreas.length === 0) {
+        throw new Error("No delivery areas specified.");
+    }
+    const areasParam = requestedAreas.join(",");
+    const cacheKey = `nordpool:${date}:${areasParam}:${currency}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const url = `https://dataportal-api.nordpoolgroup.com/api/DayAheadPrices` +
+        `?date=${date}&market=DayAhead&deliveryArea=${areasParam}&currency=${currency}`;
+    const response = await fetch(url, {
+        headers: { "User-Agent": "luminus-mcp/0.2" },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Nordpool API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const data = (await response.json());
+    if (!data.multiAreaEntries || data.multiAreaEntries.length === 0) {
+        throw new Error(`No day-ahead prices returned for areas ${areasParam} on ${date}. Data may not be available yet.`);
+    }
+    const areas = {};
+    for (const area of requestedAreas) {
+        const prices = [];
+        for (const entry of data.multiAreaEntries) {
+            const value = entry.entryPerArea[area];
+            if (value == null || !Number.isFinite(value))
+                continue;
+            prices.push({
+                timestamp: entry.deliveryStart,
+                price: Math.round(value * 100) / 100,
+            });
+        }
+        if (prices.length === 0)
+            continue;
+        const values = prices.map((p) => p.price);
+        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;
+        areas[area] = { prices, stats: { min, max, mean } };
+    }
+    if (Object.keys(areas).length === 0) {
+        throw new Error(`No price data found for the requested areas on ${date}.`);
+    }
+    const result = { date, currency, areas };
+    cache.set(cacheKey, result, TTL.PRICES);
+    return result;
+}

package/dist/tools/outages.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const outagesSchema: z.ZodObject<{
+    zone: z.ZodString;
+    type: z.ZodEnum<{
+        generation: "generation";
+        transmission: "transmission";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface OutageEntry {
+    unit_name: string;
+    fuel_type: string | null;
+    available_mw: number | null;
+    unavailable_mw: number | null;
+    nominal_mw: number | null;
+    start_date: string;
+    end_date: string;
+    reason: string | null;
+    outage_type: string;
+}
+export declare function getOutages(params: z.infer<typeof outagesSchema>): Promise<{
+    zone: string;
+    type: string;
+    outages: OutageEntry[];
+    total_unavailable_mw: number;
+    count: number;
+}>;
+export {};

package/dist/tools/outages.js

@@ -0,0 +1,107 @@
+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",
+    B07: "Oil shale",
+    B08: "Peat",
+    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 outagesSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Country/zone code. Available: ${AVAILABLE_ZONES}`),
+    type: z
+        .enum(["generation", "transmission"])
+        .describe("Type of outage: 'generation' for power plant outages, 'transmission' for grid outages."),
+    date: z
+        .string()
+        .optional()
+        .describe("Start date in YYYY-MM-DD format. Returns outages active within 7 days from this date. Defaults to today."),
+});
+export async function getOutages(params) {
+    const eic = resolveZone(params.zone);
+    const documentType = params.type === "generation" ? "A80" : "A78";
+    const base = params.date ? new Date(params.date + "T00:00:00Z") : new Date();
+    const start = new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth(), base.getUTCDate()));
+    const end = new Date(start.getTime() + 7 * 24 * 60 * 60 * 1000);
+    const queryParams = {
+        documentType,
+        periodStart: formatEntsoeDate(start),
+        periodEnd: formatEntsoeDate(end),
+    };
+    if (params.type === "generation") {
+        queryParams.biddingZone_Domain = eic;
+    }
+    else {
+        queryParams.in_Domain = eic;
+        queryParams.out_Domain = eic;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = await queryEntsoe(queryParams, TTL.OUTAGES);
+    const doc = data.Unavailability_MarketDocument;
+    if (!doc)
+        throw new Error("No outage data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const outages = [];
+    for (const ts of timeSeries) {
+        const resource = ts.production_RegisteredResource ?? ts.Asset_RegisteredResource ?? {};
+        const unitName = resource.name ?? resource.mRID ?? "Unknown";
+        const psrCode = resource.pSRType?.psrType ?? null;
+        const fuelType = 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" ? "forced" : 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 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
+            ? nominalMw - availableMw
+            : null;
+        outages.push({
+            unit_name: unitName,
+            fuel_type: fuelType,
+            available_mw: availableMw,
+            unavailable_mw: unavailableMw,
+            nominal_mw: nominalMw,
+            start_date: startDate,
+            end_date: endDate,
+            reason,
+            outage_type: outageType,
+        });
+    }
+    const totalUnavailable = outages.reduce((sum, o) => sum + (o.unavailable_mw ?? 0), 0);
+    return {
+        zone: params.zone.toUpperCase(),
+        type: params.type,
+        outages,
+        total_unavailable_mw: totalUnavailable,
+        count: outages.length,
+    };
+}

package/dist/tools/power-plants.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const powerPlantsSchema: z.ZodObject<{
+    country: z.ZodOptional<z.ZodString>;
+    fuel_type: z.ZodOptional<z.ZodString>;
+    min_capacity_mw: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface PowerPlant {
+    name: string;
+    country: string;
+    capacity_mw: number;
+    fuel: string;
+    lat: number | null;
+    lon: number | null;
+    commissioned_year: number | null;
+}
+export declare function getPowerPlants(params: z.infer<typeof powerPlantsSchema>): Promise<{
+    filters: {
+        country?: string;
+        fuel_type?: string;
+        min_capacity_mw: number;
+    };
+    total_count: number;
+    plants: PowerPlant[];
+    total_capacity_mw: number;
+}>;
+export {};