@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/tools/compare-sites.js

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { screenSite, EU_COUNTRY_CODES } from "./screen-site.js";
+// --- Schema ---
+const siteInputSchema = z.object({
+    lat: z.number().describe("Latitude (-90 to 90). WGS84."),
+    lon: z.number().describe("Longitude (-180 to 180). WGS84."),
+    label: z.string().optional().describe("Optional human-readable label for this site."),
+});
+export const compareSitesSchema = z.object({
+    sites: z
+        .array(siteInputSchema)
+        .describe("Array of candidate sites to compare (2-10)."),
+    country: z
+        .string()
+        .describe('ISO 3166-1 alpha-2 country code. "GB" and EU member states are supported.'),
+    radius_km: z
+        .number()
+        .optional()
+        .describe("Search radius in km for grid and constraints (default 2, max 10)."),
+});
+// --- Scoring heuristics ---
+/**
+ * Explicit, conservative ranking heuristics.
+ *
+ * 1. Verdict tier: pass (3) > warn (2) > fail (1). Hard constraints disqualify.
+ * 2. Solar resource: higher annual irradiance is better (normalised 0-1 within the set).
+ * 3. Grid proximity: closer to nearest substation or HV line is better (normalised 0-1, inverted).
+ * 4. Terrain flatness: lower slope is better (normalised 0-1, inverted).
+ *
+ * Weights are explicit constants. The composite score is a weighted sum.
+ */
+const VERDICT_SCORES = { pass: 3, warn: 2, fail: 1 };
+const WEIGHT_VERDICT = 40;
+const WEIGHT_SOLAR = 30;
+const WEIGHT_GRID = 20;
+const WEIGHT_TERRAIN = 10;
+const HEURISTICS_USED = [
+    `Verdict tier (weight ${WEIGHT_VERDICT}%): pass=3, warn=2, fail=1. Hard constraints and high flood-planning risk (for example Flood Zone 3) produce fail.`,
+    `Solar resource (weight ${WEIGHT_SOLAR}%): annual irradiance (kWh/m2), higher is better. Normalised across candidates.`,
+    `Grid proximity (weight ${WEIGHT_GRID}%): min(nearest_substation_km, nearest_line_km), closer is better. Normalised across candidates.`,
+    `Terrain flatness (weight ${WEIGHT_TERRAIN}%): slope in degrees, flatter is better. Normalised across candidates.`,
+    "Missing data for a dimension scores 0 for that dimension (conservative penalty).",
+    "Ties broken by input order (stable sort).",
+];
+const DISCLAIMER = "This is an automated comparison using public data. " +
+    "Rankings reflect heuristic scoring, not commercial viability. " +
+    "Professional due diligence is required before any development decision.";
+// --- Helpers ---
+/** Normalise a value into 0-1 given min/max of the set. Higher raw = higher normalised. */
+function normaliseHigherBetter(value, min, max) {
+    if (value === null)
+        return 0;
+    if (max === min)
+        return 1;
+    return (value - min) / (max - min);
+}
+/** Normalise a value into 0-1 given min/max of the set. Lower raw = higher normalised. */
+function normaliseLowerBetter(value, min, max) {
+    if (value === null)
+        return 0;
+    if (max === min)
+        return 1;
+    return 1 - (value - min) / (max - min);
+}
+function extractSolar(screen) {
+    return screen.solar?.annual_irradiance_kwh_m2 ?? null;
+}
+function extractSlope(screen) {
+    return screen.terrain?.slope_deg ?? null;
+}
+function extractNearestGrid(screen) {
+    const sub = screen.grid?.summary?.nearest_substation_km ?? null;
+    const line = screen.grid?.summary?.nearest_line_km ?? null;
+    if (sub === null && line === null)
+        return null;
+    if (sub === null)
+        return line;
+    if (line === null)
+        return sub;
+    return Math.min(sub, line);
+}
+function extractDataGaps(screen) {
+    const gaps = [];
+    if (screen.terrain === null)
+        gaps.push("terrain");
+    if (screen.grid === null)
+        gaps.push("grid");
+    if (screen.solar === null)
+        gaps.push("solar");
+    if (screen.constraints === null)
+        gaps.push("constraints");
+    if (screen.agricultural_land === null)
+        gaps.push("agricultural_land");
+    if (screen.flood_risk === null)
+        gaps.push("flood_risk");
+    return gaps;
+}
+function buildReasoning(ranked) {
+    const parts = [];
+    if (ranked.verdict === "fail") {
+        const categories = ranked.flags.map((f) => f.category).join(", ");
+        parts.push(`Failed screening due to: ${categories || "unknown reason"}.`);
+    }
+    else if (ranked.verdict === "warn") {
+        const categories = ranked.flags.map((f) => f.category).join(", ");
+        parts.push(`Warnings present: ${categories || "see screen_site flags for details"}.`);
+    }
+    else {
+        parts.push("No blocking constraints or warnings.");
+    }
+    if (ranked.solar_kwh_m2 !== null) {
+        parts.push(`Solar: ${ranked.solar_kwh_m2} kWh/m2/yr.`);
+    }
+    if (ranked.nearest_grid_km !== null) {
+        parts.push(`Nearest grid: ${ranked.nearest_grid_km.toFixed(1)} km.`);
+    }
+    if (ranked.slope_deg !== null) {
+        parts.push(`Slope: ${ranked.slope_deg.toFixed(1)} deg.`);
+    }
+    if (ranked.data_gaps.length > 0) {
+        parts.push(`Missing data: ${ranked.data_gaps.join(", ")}.`);
+    }
+    return parts.join(" ");
+}
+// --- Main tool function ---
+export async function compareSites(params) {
+    const country = params.country.toUpperCase();
+    const radiusKm = params.radius_km;
+    if (country !== "GB" && !EU_COUNTRY_CODES.has(country)) {
+        throw new Error(`Country "${params.country}" is not supported. "GB" and EU member states are available.`);
+    }
+    if (params.sites.length < 2) {
+        throw new Error("At least 2 sites are required for comparison.");
+    }
+    if (params.sites.length > 10) {
+        throw new Error("Compare at most 10 sites per call.");
+    }
+    // Screen all sites in parallel
+    const screenResults = await Promise.allSettled(params.sites.map((site) => screenSite({
+        lat: site.lat,
+        lon: site.lon,
+        country,
+        ...(radiusKm !== undefined ? { radius_km: radiusKm } : {}),
+    })));
+    // Separate successes from failures
+    const screened = [];
+    const failedSites = [];
+    for (let i = 0; i < screenResults.length; i++) {
+        const site = params.sites[i];
+        const label = site.label ?? `Site ${i + 1}`;
+        const outcome = screenResults[i];
+        if (outcome.status === "fulfilled") {
+            screened.push({ index: i, label, result: outcome.value });
+        }
+        else {
+            failedSites.push({
+                lat: site.lat,
+                lon: site.lon,
+                label,
+                error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason),
+            });
+        }
+    }
+    if (screened.length === 0) {
+        throw new Error("All sites failed screening. Cannot produce a comparison.");
+    }
+    // Extract raw values for normalisation
+    const solarValues = screened.map((s) => extractSolar(s.result));
+    const gridValues = screened.map((s) => extractNearestGrid(s.result));
+    const slopeValues = screened.map((s) => extractSlope(s.result));
+    const validSolars = solarValues.filter((v) => v !== null);
+    const validGrids = gridValues.filter((v) => v !== null);
+    const validSlopes = slopeValues.filter((v) => v !== null);
+    const solarMin = validSolars.length > 0 ? Math.min(...validSolars) : 0;
+    const solarMax = validSolars.length > 0 ? Math.max(...validSolars) : 0;
+    const gridMin = validGrids.length > 0 ? Math.min(...validGrids) : 0;
+    const gridMax = validGrids.length > 0 ? Math.max(...validGrids) : 0;
+    const slopeMin = validSlopes.length > 0 ? Math.min(...validSlopes) : 0;
+    const slopeMax = validSlopes.length > 0 ? Math.max(...validSlopes) : 0;
+    // Score each site
+    const scored = screened.map((s, idx) => {
+        const verdict = s.result.verdict.overall;
+        const solar = solarValues[idx];
+        const grid = gridValues[idx];
+        const slope = slopeValues[idx];
+        const constraintCount = s.result.constraints?.summary?.constraint_count ?? 0;
+        const dataGaps = extractDataGaps(s.result);
+        const verdictNorm = VERDICT_SCORES[verdict] / 3; // 0.33 - 1.0
+        const solarNorm = normaliseHigherBetter(solar, solarMin, solarMax);
+        const gridNorm = normaliseLowerBetter(grid, gridMin, gridMax);
+        const slopeNorm = normaliseLowerBetter(slope, slopeMin, slopeMax);
+        const score = WEIGHT_VERDICT * verdictNorm +
+            WEIGHT_SOLAR * solarNorm +
+            WEIGHT_GRID * gridNorm +
+            WEIGHT_TERRAIN * slopeNorm;
+        return {
+            index: s.index,
+            label: s.label,
+            lat: s.result.lat,
+            lon: s.result.lon,
+            verdict,
+            flag_count: s.result.verdict.flags?.length ?? 0,
+            flags: s.result.verdict.flags ?? [],
+            solar_kwh_m2: solar,
+            slope_deg: slope,
+            nearest_grid_km: grid,
+            constraint_count: constraintCount,
+            score: Math.round(score * 100) / 100,
+            data_gaps: dataGaps,
+        };
+    });
+    // Sort descending by score, stable (input order breaks ties)
+    scored.sort((a, b) => b.score - a.score);
+    // Build ranked output with reasoning
+    const rankings = scored.map((s, idx) => ({
+        rank: idx + 1,
+        label: s.label,
+        lat: s.lat,
+        lon: s.lon,
+        verdict: s.verdict,
+        flag_count: s.flag_count,
+        solar_kwh_m2: s.solar_kwh_m2,
+        slope_deg: s.slope_deg,
+        nearest_grid_km: s.nearest_grid_km,
+        constraint_count: s.constraint_count,
+        score: s.score,
+        reasoning: buildReasoning(s),
+        data_gaps: s.data_gaps,
+    }));
+    return {
+        site_count: params.sites.length,
+        rankings,
+        failed_sites: failedSites,
+        heuristics_used: HEURISTICS_USED,
+        disclaimer: DISCLAIMER,
+    };
+}

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const demandForecastSchema: z.ZodObject<{
+    zone: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface DemandPoint {
+    hour: number;
+    mw: number;
+}
+export declare function getDemandForecast(params: z.infer<typeof demandForecastSchema>): Promise<{
+    zone: string;
+    date: string;
+    forecast: DemandPoint[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+        total_mwh: number;
+    };
+}>;
+export {};

package/dist/tools/demand-forecast.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 demandForecastSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Country/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 getDemandForecast(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: "A65",
+        processType: "A01",
+        outBiddingZone_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.FORECAST);
+    const doc = data.GL_MarketDocument;
+    if (!doc)
+        throw new Error("No demand forecast data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const forecast = [];
+    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 mw = Number(point.quantity ?? 0);
+                forecast.push({ hour: position - 1, mw });
+            }
+        }
+    }
+    forecast.sort((a, b) => a.hour - b.hour);
+    const values = forecast.map((f) => f.mw);
+    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;
+    const total_mwh = values.reduce((s, v) => s + v, 0);
+    return {
+        zone: params.zone.toUpperCase(),
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        forecast,
+        stats: { min, max, mean, total_mwh },
+    };
+}

package/dist/tools/elexon-bmrs.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const elexonBmrsSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        imbalance_prices: "imbalance_prices";
+        generation_by_fuel: "generation_by_fuel";
+        balancing_bids: "balancing_bids";
+        system_warnings: "system_warnings";
+        interconnector_flows: "interconnector_flows";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface ImbalancePriceRecord {
+    settlement_date: string;
+    settlement_period: number;
+    imbalance_price_gbp: number;
+    system_sell_price_gbp: number;
+    system_buy_price_gbp: number;
+}
+interface ImbalanceResult {
+    dataset: "imbalance_prices";
+    source: string;
+    records: ImbalancePriceRecord[];
+}
+interface FuelGenRecord {
+    fuel_type: string;
+    generation_mw: number;
+    settlement_period: number;
+}
+interface GenerationByFuelResult {
+    dataset: "generation_by_fuel";
+    source: string;
+    date: string;
+    records: FuelGenRecord[];
+}
+interface BalancingBidRecord {
+    bmu_id: string;
+    bid_offer: string;
+    level_mw: number;
+    price_gbp: number;
+    settlement_period: number;
+}
+interface BalancingBidsResult {
+    dataset: "balancing_bids";
+    source: string;
+    date: string;
+    records: BalancingBidRecord[];
+}
+interface SystemWarning {
+    warning_type: string;
+    message: string;
+    published: string;
+}
+interface SystemWarningsResult {
+    dataset: "system_warnings";
+    source: string;
+    warnings: SystemWarning[];
+}
+interface InterconnectorRecord {
+    interconnector: string;
+    flow_mw: number;
+    direction: string;
+    settlement_period: number;
+}
+interface InterconnectorResult {
+    dataset: "interconnector_flows";
+    source: string;
+    date: string;
+    records: InterconnectorRecord[];
+}
+type ElexonResult = ImbalanceResult | GenerationByFuelResult | BalancingBidsResult | SystemWarningsResult | InterconnectorResult;
+export declare function getElexonBmrs(params: z.infer<typeof elexonBmrsSchema>): Promise<ElexonResult>;
+export {};

package/dist/tools/elexon-bmrs.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const API_BASE = "https://data.elexon.co.uk/bmrs/api/v1";
+const cache = new TtlCache();
+export const elexonBmrsSchema = z.object({
+    dataset: z
+        .enum([
+        "imbalance_prices",
+        "generation_by_fuel",
+        "balancing_bids",
+        "system_warnings",
+        "interconnector_flows",
+    ])
+        .describe('"imbalance_prices" = GB settlement-period imbalance/cashout prices. ' +
+        '"generation_by_fuel" = half-hourly generation by fuel type (MW). ' +
+        '"balancing_bids" = balancing mechanism bids and offers. ' +
+        '"system_warnings" = system operator warnings and notifications. ' +
+        '"interconnector_flows" = cross-border interconnector flows (MW).'),
+    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 fetchBmrs(path) {
+    const url = `${API_BASE}${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 returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    cache.set(url, json, TTL.BALANCING);
+    return json;
+}
+async function fetchImbalancePrices(date) {
+    const data = await fetchBmrs(`/balancing/settlement/system-prices?settlementDate=${date}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    const recent = rows.slice(-24);
+    const records = recent.map((r) => ({
+        settlement_date: r.settlementDate ?? date,
+        settlement_period: Number(r.settlementPeriod ?? 0),
+        imbalance_price_gbp: Math.round((Number(r.systemSellPrice ?? 0)) * 100) / 100,
+        system_sell_price_gbp: Math.round((Number(r.systemSellPrice ?? 0)) * 100) / 100,
+        system_buy_price_gbp: Math.round((Number(r.systemBuyPrice ?? 0)) * 100) / 100,
+    }));
+    return { dataset: "imbalance_prices", source: "Elexon BMRS", records };
+}
+async function fetchGenerationByFuel(date) {
+    const data = await fetchBmrs(`/generation/outturn/summary?settlementDate=${date}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    const recent = rows.slice(-20);
+    const records = recent.map((r) => ({
+        fuel_type: r.fuelType ?? "Unknown",
+        generation_mw: Math.round(Number(r.currentMw ?? r.generation ?? 0)),
+        settlement_period: Number(r.settlementPeriod ?? 0),
+    }));
+    return { dataset: "generation_by_fuel", source: "Elexon BMRS", date, records };
+}
+async function fetchBalancingBids(date) {
+    const data = await fetchBmrs(`/balancing/physical?settlementDate=${date}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    const recent = rows.slice(-30);
+    const records = recent.map((r) => ({
+        bmu_id: r.bmUnit ?? r.nationalGridBmUnit ?? "Unknown",
+        bid_offer: r.bidOfferPairId ?? "unknown",
+        level_mw: Math.round(Number(r.levelMw ?? r.pnLevelMw ?? 0)),
+        price_gbp: Math.round((Number(r.price ?? 0)) * 100) / 100,
+        settlement_period: Number(r.settlementPeriod ?? 0),
+    }));
+    return { dataset: "balancing_bids", source: "Elexon BMRS", date, records };
+}
+async function fetchSystemWarnings() {
+    const data = await fetchBmrs(`/system/warnings?format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    const warnings = rows.slice(0, 20).map((r) => ({
+        warning_type: r.warningType ?? "unknown",
+        message: r.description ?? r.message ?? "",
+        published: r.publishTime ?? r.createdDateTime ?? "",
+    }));
+    return { dataset: "system_warnings", source: "Elexon BMRS", warnings };
+}
+async function fetchInterconnectors(date) {
+    const data = await fetchBmrs(`/generation/outturn/interconnectors?settlementDate=${date}&format=json`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rows = data?.data ?? [];
+    const recent = rows.slice(-20);
+    const records = recent.map((r) => ({
+        interconnector: r.interconnectorName ?? r.interconnectorId ?? "Unknown",
+        flow_mw: Math.round(Number(r.generation ?? r.estimate ?? 0)),
+        direction: Number(r.generation ?? 0) >= 0 ? "import" : "export",
+        settlement_period: Number(r.settlementPeriod ?? 0),
+    }));
+    return { dataset: "interconnector_flows", source: "Elexon BMRS", date, records };
+}
+export async function getElexonBmrs(params) {
+    const date = params.date ?? new Date().toISOString().slice(0, 10);
+    switch (params.dataset) {
+        case "imbalance_prices":
+            return fetchImbalancePrices(date);
+        case "generation_by_fuel":
+            return fetchGenerationByFuel(date);
+        case "balancing_bids":
+            return fetchBalancingBids(date);
+        case "system_warnings":
+            return fetchSystemWarnings();
+        case "interconnector_flows":
+            return fetchInterconnectors(date);
+    }
+}

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

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const energiDataSchema: z.ZodObject<{
+    dataset: z.ZodEnum<{
+        co2_emissions: "co2_emissions";
+        electricity_production: "electricity_production";
+        electricity_prices: "electricity_prices";
+        electricity_balance: "electricity_balance";
+    }>;
+    zone: z.ZodOptional<z.ZodEnum<{
+        DK1: "DK1";
+        DK2: "DK2";
+        DK: "DK";
+    }>>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface Co2Record {
+    timestamp: string;
+    zone: string;
+    co2_gkwh: number;
+}
+interface Co2Result {
+    dataset: "co2_emissions";
+    source: string;
+    zone: string;
+    records: Co2Record[];
+}
+interface ProductionRecord {
+    timestamp: string;
+    zone: string;
+    wind_onshore_mw: number;
+    wind_offshore_mw: number;
+    solar_mw: number;
+    thermal_mw: number;
+    hydro_mw: number;
+    total_mw: number;
+}
+interface ProductionResult {
+    dataset: "electricity_production";
+    source: string;
+    zone: string;
+    records: ProductionRecord[];
+}
+interface PriceRecord {
+    timestamp: string;
+    zone: string;
+    price_eur_mwh: number;
+    price_dkk_mwh: number;
+}
+interface PricesResult {
+    dataset: "electricity_prices";
+    source: string;
+    zone: string;
+    records: PriceRecord[];
+}
+interface BalanceRecord {
+    timestamp: string;
+    zone: string;
+    production_mwh: number;
+    consumption_mwh: number;
+    import_mwh: number;
+    export_mwh: number;
+    net_exchange_mwh: number;
+}
+interface BalanceResult {
+    dataset: "electricity_balance";
+    source: string;
+    zone: string;
+    records: BalanceRecord[];
+}
+type EnergiDataResult = Co2Result | ProductionResult | PricesResult | BalanceResult;
+export declare function getEnergiData(params: z.infer<typeof energiDataSchema>): Promise<EnergiDataResult>;
+export {};