@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/lib/overpass.js

@@ -0,0 +1,193 @@
+const OVERPASS_ENDPOINTS = [
+    "https://overpass-api.de/api/interpreter",
+    "https://overpass.kumi.systems/api/interpreter",
+    "https://overpass.private.coffee/api/interpreter",
+];
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const MAX_CONCURRENT = 2;
+const MAX_PER_WINDOW = 10;
+const WINDOW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 4_000;
+const FALLBACK_DELAY_MS = 200;
+const state = {
+    windowTimestamps: [],
+    inFlight: 0,
+    queue: [],
+};
+let windowDrainTimer = null;
+/** Exposed for testing only. */
+export function _getOverpassState() {
+    return {
+        windowTimestamps: state.windowTimestamps,
+        inFlight: state.inFlight,
+        queueLength: state.queue.length,
+        maxConcurrent: MAX_CONCURRENT,
+        maxPerWindow: MAX_PER_WINDOW,
+        windowMs: WINDOW_MS,
+        requestTimeoutMs: REQUEST_TIMEOUT_MS,
+    };
+}
+/** Exposed for testing: reset internal state between test runs. */
+export function _resetOverpassState() {
+    state.windowTimestamps.length = 0;
+    state.inFlight = 0;
+    state.queue.length = 0;
+    if (windowDrainTimer) {
+        clearTimeout(windowDrainTimer);
+        windowDrainTimer = null;
+    }
+}
+function pruneWindow(now) {
+    const cutoff = now - WINDOW_MS;
+    while (state.windowTimestamps.length > 0 && state.windowTimestamps[0] < cutoff) {
+        state.windowTimestamps.shift();
+    }
+}
+function canProceed(now) {
+    pruneWindow(now);
+    return state.inFlight < MAX_CONCURRENT && state.windowTimestamps.length < MAX_PER_WINDOW;
+}
+function scheduleWindowDrain() {
+    if (state.queue.length === 0 || windowDrainTimer) {
+        return;
+    }
+    const now = Date.now();
+    pruneWindow(now);
+    if (state.windowTimestamps.length < MAX_PER_WINDOW) {
+        return;
+    }
+    const oldest = state.windowTimestamps[0];
+    const delayMs = Math.max(1, oldest + WINDOW_MS - now);
+    windowDrainTimer = setTimeout(() => {
+        windowDrainTimer = null;
+        drainQueue();
+    }, delayMs);
+}
+function drainQueue() {
+    if (windowDrainTimer) {
+        clearTimeout(windowDrainTimer);
+        windowDrainTimer = null;
+    }
+    while (state.queue.length > 0 && canProceed(Date.now())) {
+        const next = state.queue.shift();
+        next?.();
+    }
+    scheduleWindowDrain();
+}
+async function acquireSlot() {
+    if (canProceed(Date.now())) {
+        state.inFlight++;
+        state.windowTimestamps.push(Date.now());
+        return;
+    }
+    // Wait in queue until a slot opens
+    await new Promise((resolve) => {
+        state.queue.push(() => {
+            state.inFlight++;
+            state.windowTimestamps.push(Date.now());
+            resolve();
+        });
+        scheduleWindowDrain();
+    });
+}
+function releaseSlot() {
+    state.inFlight--;
+    drainQueue();
+}
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+const EXPENSIVE_QUERY_PATTERNS = [
+    "runtime error",
+    "out of memory",
+    "timed out",
+    "Query run out of memory",
+    "Query timed out",
+    "The server is probably too busy",
+    "load average",
+];
+function isQueryTooExpensive(body) {
+    const lower = body.toLowerCase();
+    return EXPENSIVE_QUERY_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function backoffMs(attempt) {
+    return Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+}
+// ---------------------------------------------------------------------------
+// Public API  (signature unchanged)
+// ---------------------------------------------------------------------------
+export async function fetchOverpassJson(query) {
+    await acquireSlot();
+    try {
+        return await fetchWithFallbacks(query);
+    }
+    finally {
+        releaseSlot();
+    }
+}
+async function fetchWithFallbacks(query) {
+    const errors = [];
+    for (let i = 0; i < OVERPASS_ENDPOINTS.length; i++) {
+        const endpoint = OVERPASS_ENDPOINTS[i];
+        // Brief delay between fallback endpoint attempts (not before the first)
+        if (i > 0) {
+            await sleep(FALLBACK_DELAY_MS);
+        }
+        // Exponential backoff: attempt index drives the delay
+        if (i > 0) {
+            await sleep(backoffMs(i - 1));
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: `data=${encodeURIComponent(query)}`,
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (response.ok) {
+                return (await response.json());
+            }
+            const body = await response.text();
+            errors.push(`${endpoint} -> ${response.status}: ${body.slice(0, 180)}`);
+            // Non-retryable status: throw immediately, no fallback
+            if (!RETRYABLE_STATUS.has(response.status)) {
+                if (isQueryTooExpensive(body)) {
+                    throw new Error(`Overpass query too expensive (${response.status} from ${endpoint}): ${body.slice(0, 300)}`);
+                }
+                throw new Error(`Overpass API returned ${response.status}: ${body.slice(0, 300)}`);
+            }
+        }
+        catch (err) {
+            clearTimeout(timeout);
+            // Re-throw non-retryable errors (our own thrown errors above)
+            if (err instanceof Error && err.message.startsWith("Overpass")) {
+                throw err;
+            }
+            // AbortController timeout
+            if (err instanceof DOMException && err.name === "AbortError") {
+                errors.push(`${endpoint} -> timeout after ${REQUEST_TIMEOUT_MS}ms`);
+                continue;
+            }
+            // AbortError can also come as a plain Error in some runtimes
+            if (err instanceof Error && err.name === "AbortError") {
+                errors.push(`${endpoint} -> timeout after ${REQUEST_TIMEOUT_MS}ms`);
+                continue;
+            }
+            // Network error or other transient failure
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`${endpoint} -> network error: ${msg}`);
+        }
+    }
+    throw new Error(`Overpass API failed across all endpoints:\n  ${errors.join("\n  ")}`);
+}

package/dist/lib/profiles.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool profiles for conditional MCP tool registration.
+ *
+ * Each profile groups tools by use case so callers can register
+ * only the subset they need, cutting context window cost from a large
+ * all-tools surface to a few hundred tokens for focused profiles.
+ */
+/** Profile name -> list of tool names that belong to it. */
+export declare const PROFILES: Readonly<Record<string, readonly string[]>>;
+/**
+ * Resolve a profile name to its tool list.
+ * Returns `null` for "full" (meaning all tools should be registered).
+ * Returns `undefined` if the profile name is unknown.
+ */
+export declare function resolveProfile(name: string): string[] | null | undefined;
+/** Return all known profile names (excluding "full"). */
+export declare function getProfileNames(): string[];
+/** One-line description for a profile. Falls back to empty string for unknown profiles. */
+export declare function getProfileDescription(name: string): string;
+/** Check whether a profile name is valid (including "full"). */
+export declare function isValidProfile(name: string): boolean;
+/** Total number of unique tools (derived from all profile entries + unassigned). */
+export declare const TOTAL_TOOLS: number;

package/dist/lib/profiles.js

@@ -0,0 +1,149 @@
+/**
+ * Tool profiles for conditional MCP tool registration.
+ *
+ * Each profile groups tools by use case so callers can register
+ * only the subset they need, cutting context window cost from a large
+ * all-tools surface to a few hundred tokens for focused profiles.
+ */
+/** Profile name -> list of tool names that belong to it. */
+export const PROFILES = {
+    trader: [
+        'get_day_ahead_prices',
+        'get_intraday_prices',
+        'get_balancing_prices',
+        'get_imbalance_prices',
+        'get_intraday_da_spread',
+        'get_commodity_prices',
+        'get_price_spread_analysis',
+        'get_nordpool_prices',
+    ],
+    grid: [
+        'get_cross_border_flows',
+        'get_net_positions',
+        'get_transfer_capacities',
+        'get_outages',
+        'get_eu_frequency',
+        'get_transmission_lines',
+        'get_power_plants',
+        'get_auction_results',
+        'get_remit_messages',
+        'get_acer_remit',
+        'get_grid_connection_queue',
+    ],
+    generation: [
+        'get_generation_mix',
+        'get_realtime_generation',
+        'get_carbon_intensity',
+        'get_renewable_forecast',
+        'get_demand_forecast',
+        'get_hydro_reservoir',
+    ],
+    gas: [
+        'get_gas_storage',
+        'get_lng_terminals',
+        'get_us_gas_data',
+        'get_eu_gas_price',
+        'get_entsog_data',
+    ],
+    renewables: [
+        'get_renewable_forecast',
+        'get_solar_irradiance',
+        'get_weather_forecast',
+        'get_era5_weather',
+        'get_hydro_inflows',
+    ],
+    uk: [
+        'get_uk_carbon_intensity',
+        'get_uk_grid_demand',
+        'get_elexon_bmrs',
+    ],
+    bess: [
+        'get_price_spread_analysis',
+        'get_ancillary_prices',
+        'get_balancing_actions',
+        'get_day_ahead_prices',
+        'get_intraday_prices',
+        'estimate_site_revenue',
+    ],
+    regional: [
+        'get_energy_charts',
+        'get_smard_data',
+        'get_rte_france',
+        'get_energi_data',
+        'get_fingrid_data',
+        'get_regelleistung',
+        'get_terna_data',
+        'get_ree_esios',
+    ],
+    weather: [
+        'get_weather_forecast',
+        'get_solar_irradiance',
+        'get_era5_weather',
+        'get_stormglass',
+        'get_hydro_inflows',
+    ],
+    gis: [
+        'get_solar_irradiance',
+        'get_transmission_lines',
+        'get_terrain_analysis',
+        'get_grid_proximity',
+        'get_grid_connection_queue',
+        'get_land_constraints',
+        'get_land_cover',
+        'get_agricultural_land',
+        'get_flood_risk',
+        'get_grid_connection_intelligence',
+        'screen_site',
+        'verify_gis_sources',
+        'compare_sites',
+        'estimate_site_revenue',
+    ],
+};
+/** Short descriptions for each profile, used by the discovery tool. */
+const PROFILE_DESCRIPTIONS = {
+    trader: 'Day-ahead, intraday, balancing, and commodity prices for energy trading',
+    grid: 'Cross-border flows, outages, transmission, auctions, connection-register signals, and grid infrastructure',
+    generation: 'Generation mix, real-time output, carbon intensity, and demand forecasts',
+    gas: 'Gas storage, LNG terminals, US gas data, EU gas prices, and ENTSOG pipelines',
+    renewables: 'Wind/solar forecasts, irradiance, ERA5 reanalysis, and hydro inflows',
+    uk: 'UK-specific carbon intensity, grid demand, and Elexon BMRS data',
+    bess: 'Battery storage arbitrage: spreads, ancillary prices, and balancing actions',
+    regional: 'Country-specific sources: Energy Charts, SMARD, RTE, Energinet, Fingrid, Terna, REE',
+    weather: 'Weather forecasts, solar irradiance, ERA5 reanalysis, and marine/offshore data',
+    gis: 'GIS site prospecting: solar resource, terrain, grid proximity, GB transmission connection-register signals, GB grid connection intelligence (GSP + TEC + substations), land constraints, land cover, agricultural-land screening, flood-risk screening, composite site screening (GB + EU), multi-site comparison (GB + EU), and source verification',
+    full: 'All 54 data tools registered by default, plus 2 meta-tools',
+};
+/**
+ * Resolve a profile name to its tool list.
+ * Returns `null` for "full" (meaning all tools should be registered).
+ * Returns `undefined` if the profile name is unknown.
+ */
+export function resolveProfile(name) {
+    if (name === 'full')
+        return null;
+    const tools = PROFILES[name];
+    if (!tools)
+        return undefined;
+    return [...tools];
+}
+/** Return all known profile names (excluding "full"). */
+export function getProfileNames() {
+    return Object.keys(PROFILES);
+}
+/** One-line description for a profile. Falls back to empty string for unknown profiles. */
+export function getProfileDescription(name) {
+    return PROFILE_DESCRIPTIONS[name] ?? '';
+}
+/** Check whether a profile name is valid (including "full"). */
+export function isValidProfile(name) {
+    return name === 'full' || name in PROFILES;
+}
+/** Total number of unique tools (derived from all profile entries + unassigned). */
+export const TOTAL_TOOLS = (() => {
+    const allTools = new Set();
+    for (const tools of Object.values(PROFILES)) {
+        for (const t of tools)
+            allTools.add(t);
+    }
+    return allTools.size;
+})();

package/dist/lib/schema-guard.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Defensive schema-drift guards for GIS tools that rely on external
+ * ArcGIS/API field names. Validates expected fields exist in API responses
+ * before parsing, so upstream renames fail loudly instead of silently
+ * returning bad data.
+ */
+/**
+ * Validate that an ArcGIS feature response contains the expected fields.
+ * Checks the first feature's `attributes` object. Skips validation when
+ * the features array is empty (no data is not a schema problem).
+ *
+ * @throws Error with provider name and missing field when validation fails.
+ */
+export declare function guardArcGisFields(features: Array<{
+    attributes: Record<string, unknown>;
+}>, expectedFields: readonly string[], provider: string): void;
+/**
+ * Validate that a JSON object has the expected top-level keys.
+ *
+ * @throws Error with provider name and missing field when validation fails.
+ */
+export declare function guardJsonFields(data: Record<string, unknown>, expectedFields: readonly string[], provider: string): void;

package/dist/lib/schema-guard.js

@@ -0,0 +1,38 @@
+/**
+ * Defensive schema-drift guards for GIS tools that rely on external
+ * ArcGIS/API field names. Validates expected fields exist in API responses
+ * before parsing, so upstream renames fail loudly instead of silently
+ * returning bad data.
+ */
+/**
+ * Validate that an ArcGIS feature response contains the expected fields.
+ * Checks the first feature's `attributes` object. Skips validation when
+ * the features array is empty (no data is not a schema problem).
+ *
+ * @throws Error with provider name and missing field when validation fails.
+ */
+export function guardArcGisFields(features, expectedFields, provider) {
+    if (features.length === 0)
+        return;
+    const attributes = features[0].attributes;
+    if (!attributes) {
+        throw new Error(`Schema drift detected in ${provider}: first feature has no "attributes" object. The upstream service may have changed its schema.`);
+    }
+    for (const field of expectedFields) {
+        if (!(field in attributes)) {
+            throw new Error(`Schema drift detected in ${provider}: expected field "${field}" not found in response. The upstream service may have changed its schema.`);
+        }
+    }
+}
+/**
+ * Validate that a JSON object has the expected top-level keys.
+ *
+ * @throws Error with provider name and missing field when validation fails.
+ */
+export function guardJsonFields(data, expectedFields, provider) {
+    for (const field of expectedFields) {
+        if (!(field in data)) {
+            throw new Error(`Schema drift detected in ${provider}: expected field "${field}" not found in response. The upstream service may have changed its schema.`);
+        }
+    }
+}

package/dist/lib/tool-handler.d.ts

@@ -0,0 +1,15 @@
+import { type z } from "zod";
+interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Wrap an MCP tool handler with schema validation and consistent error formatting.
+ * Keeps tool registration terse while making user-facing failures less cryptic.
+ */
+export declare function toolHandler<T extends z.ZodType>(schema: T, handler: (params: z.infer<T>) => Promise<unknown>): (params: unknown) => Promise<ToolResult>;
+export {};

package/dist/lib/tool-handler.js

@@ -0,0 +1,95 @@
+import { ZodError } from "zod";
+const DEBUG_ENV_VAR = "LUMINUS_DEBUG";
+const HELP_URL = "https://github.com/kitfunso/luminus#troubleshooting";
+function isDebugEnabled() {
+    return process.env[DEBUG_ENV_VAR] === "1";
+}
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+function normalizeError(error) {
+    if (error instanceof ZodError) {
+        return {
+            summary: `Invalid parameters. ${formatZodIssues(error)}`,
+            details: error.message,
+        };
+    }
+    const raw = error instanceof Error ? error.message : String(error);
+    const message = raw.trim() || "Unknown error";
+    const lower = message.toLowerCase();
+    if (lower.includes("environment variable is required") || lower.includes("api key")) {
+        return {
+            summary: "Configuration error. Add the required API key to your MCP env or .env file, then retry.",
+            details: message,
+        };
+    }
+    if (lower.includes("unknown zone") || lower.includes("unknown corridor")) {
+        return {
+            summary: "Invalid market identifier. Check the zone, corridor, or EIC code and retry.",
+            details: message,
+        };
+    }
+    if (lower.includes("no ") && lower.includes(" data")) {
+        return {
+            summary: "No data returned for that request. Check the market, date range, and source coverage.",
+            details: message,
+        };
+    }
+    if (lower.includes("fetch failed") ||
+        lower.includes("timeout") ||
+        lower.includes("timed out") ||
+        lower.includes("econnreset") ||
+        lower.includes("socket hang up")) {
+        return {
+            summary: "Upstream request failed or timed out. Retry shortly. If it keeps happening, enable debug output and inspect the source-specific details.",
+            details: message,
+        };
+    }
+    if (lower.includes("returned 4") || lower.includes("returned 5") || lower.includes("status")) {
+        return {
+            summary: "Upstream source returned an error. The request was valid, but the data provider rejected or failed it.",
+            details: message,
+        };
+    }
+    return {
+        summary: "Unexpected server error. Retry once. If it persists, enable debug output and inspect the raw error details.",
+        details: message,
+    };
+}
+function renderErrorMessage(error) {
+    const normalized = normalizeError(error);
+    const debug = isDebugEnabled();
+    if (debug) {
+        return `${normalized.summary}\n\nRaw error: ${normalized.details ?? "n/a"}`;
+    }
+    return `${normalized.summary}\n\nSet ${DEBUG_ENV_VAR}=1 for raw error details. Troubleshooting: ${HELP_URL}`;
+}
+/**
+ * Wrap an MCP tool handler with schema validation and consistent error formatting.
+ * Keeps tool registration terse while making user-facing failures less cryptic.
+ */
+export function toolHandler(schema, handler) {
+    return async (params) => {
+        try {
+            const parsed = schema.parse(params);
+            const result = await handler(parsed);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            if (isDebugEnabled()) {
+                console.error("[luminus] tool error", error);
+            }
+            return {
+                content: [{ type: "text", text: renderErrorMessage(error) }],
+                isError: true,
+            };
+        }
+    };
+}

package/dist/lib/xml-parser.d.ts

@@ -0,0 +1,4 @@
+/** Parse ENTSO-E XML response into JS object */
+export declare function parseXml(xml: string): Record<string, unknown>;
+/** Ensure a value is always an array (handles ENTSO-E single-vs-array quirk) */
+export declare function ensureArray<T>(value: T | T[] | undefined | null): T[];

package/dist/lib/xml-parser.js

@@ -0,0 +1,34 @@
+import { XMLParser } from "fast-xml-parser";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    // ENTSO-E quirk: single-element arrays come back as objects
+    // Force arrays for known list elements
+    isArray: (_name, jpath) => {
+        const arrayPaths = [
+            "GL_MarketDocument.TimeSeries",
+            "Publication_MarketDocument.TimeSeries",
+            "Imbalance_MarketDocument.TimeSeries",
+            "Balancing_MarketDocument.TimeSeries",
+            "Unavailability_MarketDocument.TimeSeries",
+            "UnavailabilityMarketDocument.TimeSeries",
+            "TimeSeries.Period",
+            "Period.Point",
+            "TimeSeries.Available_Period",
+            "Available_Period.Point",
+            "TimeSeries.MktPSRType.MktGeneratingUnit",
+        ];
+        const jp = String(jpath);
+        return arrayPaths.some((p) => jp.endsWith(p));
+    },
+});
+/** Parse ENTSO-E XML response into JS object */
+export function parseXml(xml) {
+    return parser.parse(xml);
+}
+/** Ensure a value is always an array (handles ENTSO-E single-vs-array quirk) */
+export function ensureArray(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}

package/dist/lib/zone-codes.d.ts

@@ -0,0 +1,12 @@
+/** ENTSO-E EIC area codes for European bidding zones */
+export declare const ZONE_CODES: Record<string, string>;
+/** Resolve a zone string to an EIC code. Accepts both "DE" and raw EIC codes. */
+export declare function resolveZone(zone: string): string;
+/** Resolve zone for price queries (uses bidding zone overrides) */
+export declare function resolvePriceZone(zone: string): string;
+/** All available zone keys for tool descriptions */
+export declare const AVAILABLE_ZONES: string;
+/** Neighbouring zones for net position calculation (cross-border flow pairs) */
+export declare const ZONE_NEIGHBOURS: Record<string, string[]>;
+/** Approximate bounding boxes [lat_min, lon_min, lat_max, lon_max] for Overpass API queries */
+export declare const COUNTRY_BBOXES: Record<string, [number, number, number, number]>;