@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/uk-carbon.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const CARBON_API = "https://api.carbonintensity.org.uk";
+const cache = new TtlCache();
+export const ukCarbonSchema = z.object({
+    action: z
+        .enum(["current", "regional", "date"])
+        .describe('"current" = national carbon intensity + generation mix. ' +
+        '"regional" = carbon intensity by GB region. ' +
+        '"date" = historical carbon intensity for a specific date (YYYY-MM-DD).'),
+    date: z
+        .string()
+        .optional()
+        .describe('Date in YYYY-MM-DD format. Required for action "date".'),
+});
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function fetchCarbon(path) {
+    const url = `${CARBON_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(`Carbon Intensity API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(url, json, TTL.REALTIME);
+    return json;
+}
+async function getCurrent() {
+    const [intensityData, genData] = await Promise.all([
+        fetchCarbon("/intensity"),
+        fetchCarbon("/generation"),
+    ]);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const intensity = intensityData?.data?.[0] ?? {};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const genMix = genData?.data?.generationmix ?? [];
+    return {
+        action: "current",
+        timestamp: intensity.from ?? new Date().toISOString(),
+        intensity_gco2_kwh: Number(intensity.intensity?.actual ?? intensity.intensity?.forecast ?? 0),
+        index: intensity.intensity?.index ?? "unknown",
+        generation_mix: genMix.map((g) => ({
+            fuel: g.fuel ?? "",
+            perc: Number(g.perc ?? 0),
+        })),
+    };
+}
+async function getRegional() {
+    const data = await fetchCarbon("/regional");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const regions = data?.data?.[0]?.regions ?? [];
+    return {
+        action: "regional",
+        timestamp: data?.data?.[0]?.from ?? new Date().toISOString(),
+        regions: regions.map((r) => ({
+            region: r.shortname ?? r.dnoregion ?? "unknown",
+            intensity_gco2_kwh: Number(r.intensity?.forecast ?? 0),
+            index: r.intensity?.index ?? "unknown",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            generation_mix: (r.generationmix ?? []).map((g) => ({
+                fuel: g.fuel ?? "",
+                perc: Number(g.perc ?? 0),
+            })),
+        })),
+    };
+}
+async function getByDate(date) {
+    const data = await fetchCarbon(`/intensity/date/${date}`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const periods = data?.data ?? [];
+    const entries = periods.map((p) => ({
+        from: p.from ?? "",
+        to: p.to ?? "",
+        intensity_forecast: Number(p.intensity?.forecast ?? 0),
+        intensity_actual: p.intensity?.actual != null ? Number(p.intensity.actual) : null,
+        index: p.intensity?.index ?? "unknown",
+    }));
+    const forecasts = entries.map((e) => e.intensity_forecast).filter((v) => v > 0);
+    const mean = forecasts.length > 0
+        ? Math.round((forecasts.reduce((s, v) => s + v, 0) / forecasts.length) * 10) / 10
+        : 0;
+    return {
+        action: "date",
+        date,
+        periods: entries,
+        stats: {
+            mean_forecast: mean,
+            min_forecast: forecasts.length > 0 ? Math.min(...forecasts) : 0,
+            max_forecast: forecasts.length > 0 ? Math.max(...forecasts) : 0,
+        },
+    };
+}
+export async function getUkCarbonIntensity(params) {
+    switch (params.action) {
+        case "current":
+            return getCurrent();
+        case "regional":
+            return getRegional();
+        case "date": {
+            if (!params.date) {
+                throw new Error('Date parameter is required for action "date".');
+            }
+            return getByDate(params.date);
+        }
+    }
+}

package/dist/tools/uk-grid.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const ukGridSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        frequency: "frequency";
+        demand: "demand";
+    }>;
+}, z.core.$strip>;
+interface DemandRecord {
+    timestamp: string;
+    settlement_period: number;
+    demand_mw: number;
+    transmission_demand_mw: number;
+}
+interface DemandResult {
+    action: "demand";
+    description: string;
+    records: DemandRecord[];
+}
+interface FrequencyResult {
+    action: "frequency";
+    description: string;
+    timestamp: string;
+    frequency_hz: number;
+    deviation_hz: number;
+}
+type UkGridResult = DemandResult | FrequencyResult;
+export declare function getUkGridDemand(params: z.infer<typeof ukGridSchema>): Promise<UkGridResult>;
+export {};

package/dist/tools/uk-grid.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const ELEXON_API = "https://data.elexon.co.uk/bmrs/api/v1";
+const cache = new TtlCache();
+export const ukGridSchema = z.object({
+    action: z
+        .enum(["demand", "frequency"])
+        .describe('"demand" = current GB demand actuals (MW) per settlement period. ' +
+        '"frequency" = real-time grid frequency (~50 Hz; deviations indicate stress).'),
+});
+// 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.REALTIME);
+    return json;
+}
+async function getDemand() {
+    const today = new Date().toISOString().slice(0, 10);
+    const data = await fetchElexon(`/demand/outturn?settlementDateFrom=${today}&settlementDateTo=${today}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    // Take last 24 periods (12 hours) for a useful window
+    const recent = rows.slice(-24);
+    const records = recent.map((r) => ({
+        timestamp: r.startTime ?? "",
+        settlement_period: Number(r.settlementPeriod ?? 0),
+        demand_mw: Number(r.initialDemandOutturn ?? 0),
+        transmission_demand_mw: Number(r.initialTransmissionSystemDemandOutturn ?? 0),
+    }));
+    return {
+        action: "demand",
+        description: "GB electricity demand outturn (MW), recent settlement periods",
+        records,
+    };
+}
+async function getFrequency() {
+    const data = await fetchElexon("/datasets/FREQ?format=json");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    if (rows.length === 0) {
+        throw new Error("No frequency data available from Elexon BMRS.");
+    }
+    // First record is the most recent
+    const row = rows[0];
+    const freq = Number(row.frequency ?? 50.0);
+    return {
+        action: "frequency",
+        description: "GB grid frequency (Hz). Nominal 50 Hz; deviations indicate grid stress.",
+        timestamp: row.measurementTime ?? new Date().toISOString(),
+        frequency_hz: Math.round(freq * 1000) / 1000,
+        deviation_hz: Math.round((freq - 50.0) * 1000) / 1000,
+    };
+}
+export async function getUkGridDemand(params) {
+    switch (params.action) {
+        case "demand":
+            return getDemand();
+        case "frequency":
+            return getFrequency();
+    }
+}

package/dist/tools/us-gas.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const usGasSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        storage: "storage";
+        henry_hub: "henry_hub";
+    }>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface StorageRecord {
+    period: string;
+    value_bcf: number;
+    region: string;
+}
+interface HenryHubRecord {
+    period: string;
+    price_usd_mmbtu: number;
+}
+interface UsGasStorageResult {
+    dataset: "storage";
+    description: string;
+    records: StorageRecord[];
+}
+interface UsGasHenryHubResult {
+    dataset: "henry_hub";
+    description: string;
+    records: HenryHubRecord[];
+}
+type UsGasResult = UsGasStorageResult | UsGasHenryHubResult;
+export declare function getUsGasData(params: z.infer<typeof usGasSchema>): Promise<UsGasResult>;
+export {};

package/dist/tools/us-gas.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { resolveApiKey } from "../lib/auth.js";
+const BASE_URL = "https://api.eia.gov/v2";
+const cache = new TtlCache();
+export const usGasSchema = z.object({
+    dataset: z
+        .enum(["storage", "henry_hub"])
+        .describe('Dataset to query. "storage" = weekly US gas storage levels (Lower 48). ' +
+        '"henry_hub" = Henry Hub natural gas spot price.'),
+    limit: z
+        .number()
+        .optional()
+        .describe("Number of records to return. Defaults to 10."),
+});
+async function getApiKey() {
+    try {
+        return await resolveApiKey("EIA_API_KEY");
+    }
+    catch {
+        throw new Error("EIA_API_KEY is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Get one at https://www.eia.gov/opendata/register.php");
+    }
+}
+async function fetchEia(path, params, ttlMs
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    const url = new URL(`${BASE_URL}${path}`);
+    url.searchParams.set("api_key", await getApiKey());
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    const cacheKey = url.toString().replace(/api_key=[^&]+/, "api_key=***");
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`EIA API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(cacheKey, json, ttlMs);
+    return json;
+}
+async function getWeeklyStorage(limit) {
+    // EIA v2 requires /data/ suffix for data queries
+    // Filter: R48 = Lower 48 total, SWO = Working Gas
+    const data = await fetchEia("/natural-gas/stor/wkly/data/", {
+        "data[]": "value",
+        "facets[duoarea][]": "R48",
+        "facets[process][]": "SWO",
+        frequency: "weekly",
+        "sort[0][column]": "period",
+        "sort[0][direction]": "desc",
+        length: String(limit),
+    }, TTL.EIA);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.response?.data ?? [];
+    const records = rows.map((r) => ({
+        period: r.period ?? "",
+        value_bcf: Number(r.value ?? 0),
+        region: r["series-description"] ?? "Lower 48",
+    }));
+    return {
+        dataset: "storage",
+        description: "US weekly natural gas working storage, Lower 48 (Bcf)",
+        records,
+    };
+}
+async function getHenryHub(limit) {
+    const data = await fetchEia("/natural-gas/pri/fut/data/", {
+        "data[]": "value",
+        "facets[series][]": "RNGWHHD",
+        frequency: "daily",
+        "sort[0][column]": "period",
+        "sort[0][direction]": "desc",
+        length: String(limit),
+    }, TTL.EIA);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.response?.data ?? [];
+    const records = rows.map((r) => ({
+        period: r.period ?? "",
+        price_usd_mmbtu: Number(r.value ?? 0),
+    }));
+    return {
+        dataset: "henry_hub",
+        description: "Henry Hub natural gas spot price (USD/MMBtu)",
+        records,
+    };
+}
+export async function getUsGasData(params) {
+    const limit = params.limit ?? 10;
+    switch (params.dataset) {
+        case "storage":
+            return getWeeklyStorage(limit);
+        case "henry_hub":
+            return getHenryHub(limit);
+    }
+}

package/dist/tools/verify-gis-sources.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type GisSourceMetadata } from "../lib/gis-sources.js";
+export declare const verifyGisSourcesSchema: z.ZodObject<{
+    source_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface SourceCheckResult {
+    source_id: string;
+    name: string;
+    status: "ok" | "degraded" | "unreachable";
+    response_time_ms: number | null;
+    error: string | null;
+    metadata: GisSourceMetadata;
+}
+interface VerifyGisSourcesResult {
+    checked_at: string;
+    sources: SourceCheckResult[];
+    summary: {
+        total: number;
+        ok: number;
+        degraded: number;
+        unreachable: number;
+    };
+}
+export declare function verifyGisSources(params: z.infer<typeof verifyGisSourcesSchema>): Promise<VerifyGisSourcesResult>;
+export {};

package/dist/tools/verify-gis-sources.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { GIS_SOURCES, GIS_HEALTH_CHECKS, } from "../lib/gis-sources.js";
+export const verifyGisSourcesSchema = z.object({
+    source_id: z
+        .string()
+        .optional()
+        .describe('Check a single source by ID (e.g. "natural-england"). Omit to check all GIS sources.'),
+});
+async function checkSource(sourceId) {
+    const metadata = GIS_SOURCES[sourceId];
+    if (!metadata) {
+        return {
+            source_id: sourceId,
+            name: "Unknown",
+            status: "unreachable",
+            response_time_ms: null,
+            error: `No metadata defined for source "${sourceId}"`,
+            metadata: {},
+        };
+    }
+    const healthCheck = GIS_HEALTH_CHECKS.find((h) => h.source_id === sourceId);
+    if (!healthCheck) {
+        return {
+            source_id: sourceId,
+            name: metadata.name,
+            status: "degraded",
+            response_time_ms: null,
+            error: "No health check configured for this source",
+            metadata,
+        };
+    }
+    const start = Date.now();
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), healthCheck.timeout_ms);
+        const fetchOptions = {
+            method: healthCheck.method,
+            signal: controller.signal,
+        };
+        if (healthCheck.method === "POST" && healthCheck.body) {
+            fetchOptions.headers = {
+                "Content-Type": "application/x-www-form-urlencoded",
+            };
+            fetchOptions.body = healthCheck.body;
+        }
+        const response = await fetch(healthCheck.url, fetchOptions);
+        clearTimeout(timeout);
+        const elapsed = Date.now() - start;
+        const body = await response.text();
+        const validationError = healthCheck.validate(response.status, body);
+        if (validationError) {
+            return {
+                source_id: sourceId,
+                name: metadata.name,
+                status: "degraded",
+                response_time_ms: elapsed,
+                error: validationError,
+                metadata,
+            };
+        }
+        return {
+            source_id: sourceId,
+            name: metadata.name,
+            status: "ok",
+            response_time_ms: elapsed,
+            error: null,
+            metadata,
+        };
+    }
+    catch (err) {
+        const elapsed = Date.now() - start;
+        const message = err instanceof Error ? err.message : String(err);
+        const isTimeout = message.includes("abort");
+        return {
+            source_id: sourceId,
+            name: metadata.name,
+            status: "unreachable",
+            response_time_ms: isTimeout ? null : elapsed,
+            error: isTimeout
+                ? `Timed out after ${healthCheck.timeout_ms}ms`
+                : message,
+            metadata,
+        };
+    }
+}
+export async function verifyGisSources(params) {
+    const sourceIds = params.source_id
+        ? [params.source_id]
+        : Object.keys(GIS_SOURCES);
+    if (params.source_id && !GIS_SOURCES[params.source_id]) {
+        throw new Error(`Unknown source ID "${params.source_id}". Valid IDs: ${Object.keys(GIS_SOURCES).join(", ")}`);
+    }
+    const results = await Promise.allSettled(sourceIds.map((id) => checkSource(id)));
+    const sources = results.map((r, i) => {
+        if (r.status === "fulfilled")
+            return r.value;
+        return {
+            source_id: sourceIds[i],
+            name: GIS_SOURCES[sourceIds[i]]?.name ?? "Unknown",
+            status: "unreachable",
+            response_time_ms: null,
+            error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+            metadata: GIS_SOURCES[sourceIds[i]] ?? {},
+        };
+    });
+    const ok = sources.filter((s) => s.status === "ok").length;
+    const degraded = sources.filter((s) => s.status === "degraded").length;
+    const unreachable = sources.filter((s) => s.status === "unreachable").length;
+    return {
+        checked_at: new Date().toISOString(),
+        sources,
+        summary: {
+            total: sources.length,
+            ok,
+            degraded,
+            unreachable,
+        },
+    };
+}

package/dist/tools/weather.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const weatherSchema: z.ZodObject<{
+    country: z.ZodOptional<z.ZodString>;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface HourlyPoint {
+    time: string;
+    temperature_c: number;
+    wind_speed_kmh: number;
+    solar_radiation_wm2: number;
+}
+interface WeatherResult {
+    location: string;
+    latitude: number;
+    longitude: number;
+    hourly: HourlyPoint[];
+    stats: {
+        temp_min_c: number;
+        temp_max_c: number;
+        temp_mean_c: number;
+        wind_mean_kmh: number;
+        solar_mean_wm2: number;
+    };
+}
+export declare function getWeatherForecast(params: z.infer<typeof weatherSchema>): Promise<WeatherResult>;
+export {};

package/dist/tools/weather.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const BASE_URL = "https://api.open-meteo.com/v1/forecast";
+const cache = new TtlCache();
+/** Capital city coordinates for default weather lookups */
+const CAPITAL_COORDS = {
+    AT: { lat: 48.21, lon: 16.37, city: "Vienna" },
+    BE: { lat: 50.85, lon: 4.35, city: "Brussels" },
+    BG: { lat: 42.70, lon: 23.32, city: "Sofia" },
+    CH: { lat: 46.95, lon: 7.45, city: "Bern" },
+    CZ: { lat: 50.08, lon: 14.42, city: "Prague" },
+    DE: { lat: 52.52, lon: 13.41, city: "Berlin" },
+    DK: { lat: 55.68, lon: 12.57, city: "Copenhagen" },
+    EE: { lat: 59.44, lon: 24.75, city: "Tallinn" },
+    ES: { lat: 40.42, lon: -3.70, city: "Madrid" },
+    FI: { lat: 60.17, lon: 24.94, city: "Helsinki" },
+    FR: { lat: 48.86, lon: 2.35, city: "Paris" },
+    GB: { lat: 51.51, lon: -0.13, city: "London" },
+    GR: { lat: 37.98, lon: 23.73, city: "Athens" },
+    HR: { lat: 45.81, lon: 15.98, city: "Zagreb" },
+    HU: { lat: 47.50, lon: 19.04, city: "Budapest" },
+    IE: { lat: 53.35, lon: -6.26, city: "Dublin" },
+    IT: { lat: 41.90, lon: 12.50, city: "Rome" },
+    LT: { lat: 54.69, lon: 25.28, city: "Vilnius" },
+    LV: { lat: 56.95, lon: 24.11, city: "Riga" },
+    NL: { lat: 52.37, lon: 4.90, city: "Amsterdam" },
+    NO: { lat: 59.91, lon: 10.75, city: "Oslo" },
+    PL: { lat: 52.23, lon: 21.01, city: "Warsaw" },
+    PT: { lat: 38.72, lon: -9.14, city: "Lisbon" },
+    RO: { lat: 44.43, lon: 26.10, city: "Bucharest" },
+    SE: { lat: 59.33, lon: 18.07, city: "Stockholm" },
+    SI: { lat: 46.05, lon: 14.51, city: "Ljubljana" },
+    SK: { lat: 48.15, lon: 17.11, city: "Bratislava" },
+};
+export const weatherSchema = z.object({
+    country: z
+        .string()
+        .optional()
+        .describe(`Country code for capital city lookup. Available: ${Object.keys(CAPITAL_COORDS).join(", ")}. ` +
+        "Ignored if latitude/longitude are provided."),
+    latitude: z
+        .number()
+        .optional()
+        .describe("Latitude (-90 to 90). Overrides country-based lookup."),
+    longitude: z
+        .number()
+        .optional()
+        .describe("Longitude (-180 to 180). Overrides country-based lookup."),
+});
+function resolveCoords(params) {
+    if (params.latitude != null && params.longitude != null) {
+        return {
+            lat: params.latitude,
+            lon: params.longitude,
+            location: `${params.latitude},${params.longitude}`,
+        };
+    }
+    if (!params.country) {
+        throw new Error("Provide either a country code or latitude/longitude coordinates.");
+    }
+    const upper = params.country.toUpperCase();
+    const coords = CAPITAL_COORDS[upper];
+    if (!coords) {
+        throw new Error(`Unknown country "${params.country}". Available: ${Object.keys(CAPITAL_COORDS).join(", ")}`);
+    }
+    return { lat: coords.lat, lon: coords.lon, location: `${coords.city}, ${upper}` };
+}
+export async function getWeatherForecast(params) {
+    const { lat, lon, location } = resolveCoords(params);
+    const cacheKey = `weather:${lat}:${lon}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const url = new URL(BASE_URL);
+    url.searchParams.set("latitude", String(lat));
+    url.searchParams.set("longitude", String(lon));
+    url.searchParams.set("hourly", "temperature_2m,wind_speed_10m,shortwave_radiation");
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Open-Meteo API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    const h = json.hourly;
+    if (!h || !h.time) {
+        throw new Error("No hourly forecast data returned.");
+    }
+    const times = h.time;
+    const temps = h.temperature_2m;
+    const winds = h.wind_speed_10m;
+    const solar = h.shortwave_radiation;
+    const hourly = times.map((t, i) => ({
+        time: t,
+        temperature_c: temps[i] ?? 0,
+        wind_speed_kmh: winds[i] ?? 0,
+        solar_radiation_wm2: solar[i] ?? 0,
+    }));
+    const tempValues = temps.filter((v) => v != null);
+    const windValues = winds.filter((v) => v != null);
+    const solarValues = solar.filter((v) => v != null);
+    const mean = (arr) => arr.length > 0
+        ? Math.round((arr.reduce((s, v) => s + v, 0) / arr.length) * 100) / 100
+        : 0;
+    const result = {
+        location,
+        latitude: lat,
+        longitude: lon,
+        hourly,
+        stats: {
+            temp_min_c: tempValues.length > 0 ? Math.min(...tempValues) : 0,
+            temp_max_c: tempValues.length > 0 ? Math.max(...tempValues) : 0,
+            temp_mean_c: mean(tempValues),
+            wind_mean_kmh: mean(windValues),
+            solar_mean_wm2: mean(solarValues),
+        },
+    };
+    cache.set(cacheKey, result, TTL.WEATHER);
+    return result;
+}