@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/smard-data.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export declare const smardSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        generation: "generation";
+        consumption: "consumption";
+        market_price: "market_price";
+    }>;
+}, z.core.$strip>;
+interface HourlyPoint {
+    timestamp: string;
+    value: number;
+}
+interface GenerationSource {
+    fuel: string;
+    latest_mw: number;
+    hourly: HourlyPoint[];
+}
+interface SmardGenerationResult {
+    dataset: "generation";
+    source: "smard.de";
+    generation: GenerationSource[];
+    total_mw: number;
+}
+interface SmardTimeseriesResult {
+    dataset: string;
+    source: "smard.de";
+    resolution: "hourly";
+    data: HourlyPoint[];
+    latest: number;
+    unit: string;
+}
+type SmardResult = SmardGenerationResult | SmardTimeseriesResult;
+export declare function getSmardData(params: z.infer<typeof smardSchema>): Promise<SmardResult>;
+export {};

package/dist/tools/smard-data.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const cache = new TtlCache();
+const SMARD_BASE = "https://www.smard.de/app/chart_data";
+export const smardSchema = z.object({
+    dataset: z
+        .enum(["generation", "consumption", "market_price"])
+        .describe('"generation" = hourly generation by source. "consumption" = total consumption. "market_price" = day-ahead + intraday prices.'),
+});
+// SMARD filter IDs
+const FILTER_IDS = {
+    total_generation: 410,
+    total_consumption: 4169,
+    day_ahead_price: 4170,
+};
+const GENERATION_SOURCES = {
+    Biomass: 4068,
+    Hydro: 1226,
+    "Wind Offshore": 1225,
+    "Wind Onshore": 4067,
+    Solar: 4069,
+    Gas: 1228,
+    Coal: 1227,
+    Nuclear: 4071,
+};
+async function fetchSmardIndex(filterId) {
+    const cacheKey = `smard:index:${filterId}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const url = `${SMARD_BASE}/${filterId}/DE/index_hour.json`;
+        const response = await fetch(url, {
+            headers: { "User-Agent": "luminus-mcp/0.2" },
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        if (!data.timestamps || data.timestamps.length === 0)
+            return null;
+        const latest = data.timestamps[data.timestamps.length - 1];
+        cache.set(cacheKey, latest, TTL.REALTIME);
+        return latest;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchSmardSeries(filterId, timestamp) {
+    const cacheKey = `smard:data:${filterId}:${timestamp}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const url = `${SMARD_BASE}/${filterId}/DE/${filterId}_DE_hour_${timestamp}.json`;
+        const response = await fetch(url, {
+            headers: { "User-Agent": "luminus-mcp/0.2" },
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        if (!data.series || data.series.length === 0)
+            return null;
+        cache.set(cacheKey, data.series, TTL.REALTIME);
+        return data.series;
+    }
+    catch {
+        return null;
+    }
+}
+function extractLast24h(series) {
+    const now = Date.now();
+    const cutoff = now - 24 * 60 * 60 * 1000;
+    const points = [];
+    for (const [tsMs, value] of series) {
+        if (tsMs < cutoff)
+            continue;
+        if (value == null || !Number.isFinite(value))
+            continue;
+        points.push({
+            timestamp: new Date(tsMs).toISOString(),
+            value: Math.round(value * 100) / 100,
+        });
+    }
+    return points;
+}
+function latestValue(series) {
+    for (let i = series.length - 1; i >= 0; i--) {
+        const val = series[i][1];
+        if (val != null && Number.isFinite(val)) {
+            return Math.round(val * 100) / 100;
+        }
+    }
+    return 0;
+}
+async function fetchGeneration() {
+    // Fetch all generation sources in parallel
+    const entries = Object.entries(GENERATION_SOURCES);
+    const results = await Promise.all(entries.map(async ([fuel, filterId]) => {
+        const timestamp = await fetchSmardIndex(filterId);
+        if (timestamp == null)
+            return null;
+        const series = await fetchSmardSeries(filterId, timestamp);
+        if (!series)
+            return null;
+        const hourly = extractLast24h(series);
+        const latest = latestValue(series);
+        return { fuel, latest_mw: latest, hourly };
+    }));
+    const generation = results.filter((r) => r !== null && r.latest_mw > 0);
+    generation.sort((a, b) => b.latest_mw - a.latest_mw);
+    const totalMw = generation.reduce((sum, g) => sum + g.latest_mw, 0);
+    return {
+        dataset: "generation",
+        source: "smard.de",
+        generation,
+        total_mw: Math.round(totalMw),
+    };
+}
+async function fetchTimeseries(dataset) {
+    const filterId = dataset === "consumption"
+        ? FILTER_IDS.total_consumption
+        : FILTER_IDS.day_ahead_price;
+    const unit = dataset === "consumption" ? "MW" : "EUR/MWh";
+    const timestamp = await fetchSmardIndex(filterId);
+    if (timestamp == null) {
+        throw new Error(`Unable to fetch SMARD index for ${dataset}. Service may be temporarily unavailable.`);
+    }
+    const series = await fetchSmardSeries(filterId, timestamp);
+    if (!series) {
+        throw new Error(`Unable to fetch SMARD data for ${dataset}. Service may be temporarily unavailable.`);
+    }
+    const data = extractLast24h(series);
+    const latest = latestValue(series);
+    return {
+        dataset,
+        source: "smard.de",
+        resolution: "hourly",
+        data,
+        latest,
+        unit,
+    };
+}
+export async function getSmardData(params) {
+    switch (params.dataset) {
+        case "generation":
+            return fetchGeneration();
+        case "consumption":
+            return fetchTimeseries("consumption");
+        case "market_price":
+            return fetchTimeseries("market_price");
+        default:
+            throw new Error(`Unknown dataset "${params.dataset}". Use: generation, consumption, market_price.`);
+    }
+}

package/dist/tools/solar.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { type GisSourceMetadata } from "../lib/gis-sources.js";
+export declare const solarSchema: z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    year: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface MonthlyIrradiance {
+    month: number;
+    irradiance_kwh_m2: number;
+    energy_kwh: number;
+}
+interface SolarResult {
+    lat: number;
+    lon: number;
+    optimal_angle_deg: number;
+    annual_irradiance_kwh_m2: number;
+    annual_yield_kwh: number;
+    monthly: MonthlyIrradiance[];
+    source_metadata: GisSourceMetadata;
+}
+export declare function getSolarIrradiance(params: z.infer<typeof solarSchema>): Promise<SolarResult>;
+export {};

package/dist/tools/solar.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { GIS_SOURCES } from "../lib/gis-sources.js";
+const BASE_URL = "https://re.jrc.ec.europa.eu/api/v5_3";
+const cache = new TtlCache();
+export const solarSchema = z.object({
+    lat: z
+        .number()
+        .describe("Latitude (-90 to 90). Example: 48.86 for Paris."),
+    lon: z
+        .number()
+        .describe("Longitude (-180 to 180). Example: 2.35 for Paris."),
+    year: z
+        .number()
+        .optional()
+        .describe("Specific year for hourly time series (2005-2023). Omit for long-term monthly averages."),
+});
+export async function getSolarIrradiance(params) {
+    const { lat, lon, year } = params;
+    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 = `pvgis:${lat}:${lon}:${year ?? "avg"}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const url = new URL(`${BASE_URL}/PVcalc`);
+    url.searchParams.set("lat", String(lat));
+    url.searchParams.set("lon", String(lon));
+    url.searchParams.set("peakpower", "1");
+    url.searchParams.set("loss", "14");
+    url.searchParams.set("outputformat", "json");
+    if (year) {
+        url.searchParams.set("startyear", String(year));
+        url.searchParams.set("endyear", String(year));
+    }
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`PVGIS API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    const outputs = json.outputs;
+    if (!outputs)
+        throw new Error("No data returned from PVGIS for this location.");
+    const monthlyData = outputs.monthly?.fixed ?? [];
+    const totals = outputs.totals?.fixed ?? {};
+    const optimalAngle = json.inputs?.mounting_system?.fixed?.slope?.value ?? 0;
+    const monthly = monthlyData.map(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (m) => ({
+        month: m.month,
+        irradiance_kwh_m2: Number(m["H(i)_m"] ?? 0),
+        energy_kwh: Number(m.E_m ?? 0),
+    }));
+    const result = {
+        lat,
+        lon,
+        optimal_angle_deg: Number(optimalAngle),
+        annual_irradiance_kwh_m2: Number(totals["H(i)_y"] ?? 0),
+        annual_yield_kwh: Number(totals.E_y ?? 0),
+        monthly,
+        source_metadata: GIS_SOURCES["pvgis"],
+    };
+    cache.set(cacheKey, result, TTL.STATIC_DATA);
+    return result;
+}

package/dist/tools/stormglass.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export declare const stormglassSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    dataset: z.ZodOptional<z.ZodEnum<{
+        weather: "weather";
+        tide: "tide";
+    }>>;
+}, z.core.$strip>;
+interface WeatherHour {
+    timestamp: string;
+    wind_speed_ms: number;
+    wind_direction_deg: number;
+    wind_gust_ms: number;
+    wave_height_m: number;
+    wave_period_s: number;
+    wave_direction_deg: number;
+    swell_height_m: number;
+    swell_period_s: number;
+    sea_surface_temp_c: number;
+    air_temp_c: number;
+    pressure_hpa: number;
+    visibility_km: number;
+    cloud_cover_pct: number;
+}
+interface WeatherResult {
+    dataset: "weather";
+    source: string;
+    latitude: number;
+    longitude: number;
+    description: string;
+    hours: WeatherHour[];
+    summary: {
+        avg_wind_speed_ms: number;
+        max_wind_gust_ms: number;
+        avg_wave_height_m: number;
+        max_wave_height_m: number;
+        avg_sea_temp_c: number;
+        conditions: string;
+    };
+}
+interface TidePoint {
+    timestamp: string;
+    type: string;
+    height_m: number;
+}
+interface TideResult {
+    dataset: "tide";
+    source: string;
+    latitude: number;
+    longitude: number;
+    tides: TidePoint[];
+}
+type StormglassResult = WeatherResult | TideResult;
+export declare function getStormglass(params: z.infer<typeof stormglassSchema>): Promise<StormglassResult>;
+export {};

package/dist/tools/stormglass.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const API_BASE = "https://api.stormglass.io/v2";
+const cache = new TtlCache();
+const FORECAST_WINDOW_MS = 48 * 60 * 60 * 1000;
+export const stormglassSchema = z.object({
+    latitude: z.number().describe("Latitude (-90 to 90)."),
+    longitude: z.number().describe("Longitude (-180 to 180)."),
+    dataset: z
+        .enum(["weather", "tide"])
+        .optional()
+        .describe('"weather" = marine/offshore weather including wind at hub height, waves, swell (default). ' +
+        '"tide" = tidal predictions (sea level, high/low tide times).'),
+});
+async function getApiKey() {
+    try {
+        return await resolveApiKey("STORMGLASS_API_KEY");
+    }
+    catch {
+        throw new Error("STORMGLASS_API_KEY is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Get a free key at https://stormglass.io/ (10 requests/day on free tier).");
+    }
+}
+function alignToBucket(date, bucketMs) {
+    return new Date(Math.floor(date.getTime() / bucketMs) * bucketMs);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function pickSource(obj) {
+    // Storm Glass returns data from multiple sources; pick the best available
+    if (typeof obj === "number")
+        return obj;
+    if (obj?.sg != null)
+        return Number(obj.sg);
+    if (obj?.noaa != null)
+        return Number(obj.noaa);
+    if (obj?.dwd != null)
+        return Number(obj.dwd);
+    if (obj?.icon != null)
+        return Number(obj.icon);
+    const vals = Object.values(obj ?? {}).filter((v) => typeof v === "number");
+    return vals.length > 0 ? vals[0] : 0;
+}
+function buildWeatherUrl(lat, lon) {
+    const params = [
+        "windSpeed",
+        "windDirection",
+        "gust",
+        "waveHeight",
+        "wavePeriod",
+        "waveDirection",
+        "swellHeight",
+        "swellPeriod",
+        "waterTemperature",
+        "airTemperature",
+        "pressure",
+        "visibility",
+        "cloudCover",
+    ].join(",");
+    const start = alignToBucket(new Date(), TTL.WEATHER);
+    const end = new Date(start.getTime() + FORECAST_WINDOW_MS);
+    return (`${API_BASE}/weather/point?lat=${lat}&lng=${lon}` +
+        `&params=${params}` +
+        `&start=${start.toISOString()}&end=${end.toISOString()}`);
+}
+async function fetchWeather(lat, lon) {
+    const url = buildWeatherUrl(lat, lon);
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = await fetch(url, {
+        headers: { Authorization: await getApiKey() },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Storm Glass API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rawHours = json?.hours ?? [];
+    const hours = rawHours.slice(0, 48).map((h) => ({
+        timestamp: h.time ?? "",
+        wind_speed_ms: Math.round(pickSource(h.windSpeed) * 10) / 10,
+        wind_direction_deg: Math.round(pickSource(h.windDirection)),
+        wind_gust_ms: Math.round(pickSource(h.gust) * 10) / 10,
+        wave_height_m: Math.round(pickSource(h.waveHeight) * 100) / 100,
+        wave_period_s: Math.round(pickSource(h.wavePeriod) * 10) / 10,
+        wave_direction_deg: Math.round(pickSource(h.waveDirection)),
+        swell_height_m: Math.round(pickSource(h.swellHeight) * 100) / 100,
+        swell_period_s: Math.round(pickSource(h.swellPeriod) * 10) / 10,
+        sea_surface_temp_c: Math.round(pickSource(h.waterTemperature) * 10) / 10,
+        air_temp_c: Math.round(pickSource(h.airTemperature) * 10) / 10,
+        pressure_hpa: Math.round(pickSource(h.pressure) * 10) / 10,
+        visibility_km: Math.round(pickSource(h.visibility) * 10) / 10,
+        cloud_cover_pct: Math.round(pickSource(h.cloudCover)),
+    }));
+    const windSpeeds = hours.map((h) => h.wind_speed_ms);
+    const gusts = hours.map((h) => h.wind_gust_ms);
+    const waves = hours.map((h) => h.wave_height_m);
+    const seaTemps = hours.filter((h) => h.sea_surface_temp_c !== 0).map((h) => h.sea_surface_temp_c);
+    const avg = (arr) => arr.length > 0 ? Math.round((arr.reduce((s, v) => s + v, 0) / arr.length) * 10) / 10 : 0;
+    const avgWind = avg(windSpeeds);
+    const maxWave = waves.length > 0 ? Math.round(Math.max(...waves) * 100) / 100 : 0;
+    let conditions = "Calm";
+    if (avgWind > 15)
+        conditions = "Storm conditions — offshore operations likely suspended";
+    else if (avgWind > 10)
+        conditions = "Strong winds — challenging for offshore maintenance";
+    else if (avgWind > 6)
+        conditions = "Moderate winds — good for wind generation";
+    else if (avgWind > 3)
+        conditions = "Light winds — reduced wind output";
+    const result = {
+        dataset: "weather",
+        source: "Storm Glass (marine/offshore weather)",
+        latitude: lat,
+        longitude: lon,
+        description: "48-hour marine weather forecast. Key for offshore wind assessment and maintenance windows.",
+        hours,
+        summary: {
+            avg_wind_speed_ms: avgWind,
+            max_wind_gust_ms: gusts.length > 0 ? Math.round(Math.max(...gusts) * 10) / 10 : 0,
+            avg_wave_height_m: avg(waves),
+            max_wave_height_m: maxWave,
+            avg_sea_temp_c: avg(seaTemps),
+            conditions,
+        },
+    };
+    cache.set(url, result, TTL.WEATHER);
+    return result;
+}
+async function fetchTide(lat, lon) {
+    const url = `${API_BASE}/tide/extremes/point?lat=${lat}&lng=${lon}`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    const response = await fetch(url, {
+        headers: { Authorization: await getApiKey() },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Storm Glass Tide API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rawTides = json?.data ?? [];
+    const tides = rawTides.slice(0, 20).map((t) => ({
+        timestamp: t.time ?? "",
+        type: t.type ?? "unknown",
+        height_m: Math.round((Number(t.height ?? 0)) * 100) / 100,
+    }));
+    const result = {
+        dataset: "tide",
+        source: "Storm Glass (tidal predictions)",
+        latitude: lat,
+        longitude: lon,
+        tides,
+    };
+    cache.set(url, result, TTL.WEATHER);
+    return result;
+}
+export async function getStormglass(params) {
+    const dataset = params.dataset ?? "weather";
+    switch (dataset) {
+        case "weather":
+            return fetchWeather(params.latitude, params.longitude);
+        case "tide":
+            return fetchTide(params.latitude, params.longitude);
+    }
+}

package/dist/tools/terna.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+export declare const ternaSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        generation: "generation";
+        demand: "demand";
+        exchanges: "exchanges";
+        market_data: "market_data";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+    zone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface GenerationRecord {
+    timestamp: string;
+    thermal_mw: number;
+    hydro_mw: number;
+    wind_mw: number;
+    solar_mw: number;
+    geothermal_mw: number;
+    biomass_mw: number;
+    total_mw: number;
+    renewable_pct: number;
+}
+interface TernaGenerationResult {
+    dataset: "generation";
+    source: string;
+    date: string;
+    zone: string;
+    records: GenerationRecord[];
+    latest: GenerationRecord | null;
+}
+interface DemandRecord {
+    timestamp: string;
+    demand_mw: number;
+    forecast_mw: number;
+}
+interface TernaDemandResult {
+    dataset: "demand";
+    source: string;
+    date: string;
+    zone: string;
+    records: DemandRecord[];
+}
+interface ExchangeRecord {
+    border: string;
+    flow_mw: number;
+    direction: string;
+}
+interface TernaExchangesResult {
+    dataset: "exchanges";
+    source: string;
+    date: string;
+    exchanges: ExchangeRecord[];
+    net_import_mw: number;
+}
+interface MarketRecord {
+    zone: string;
+    timestamp: string;
+    price_eur_mwh: number;
+}
+interface TernaMarketResult {
+    dataset: "market_data";
+    source: string;
+    date: string;
+    zone: string;
+    records: MarketRecord[];
+}
+type TernaResult = TernaGenerationResult | TernaDemandResult | TernaExchangesResult | TernaMarketResult;
+export declare function getTernaData(params: z.infer<typeof ternaSchema>): Promise<TernaResult>;
+export {};