@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/lib/zone-codes.js

@@ -0,0 +1,127 @@
+/** ENTSO-E EIC area codes for European bidding zones */
+export const ZONE_CODES = {
+    GB: "10YGB----------A",
+    DE: "10Y1001A1001A83F",
+    DE_LU: "10Y1001A1001A82H", // DE-LU combined bidding zone (used for prices)
+    FR: "10YFR-RTE------C",
+    NL: "10YNL----------L",
+    BE: "10YBE----------2",
+    ES: "10YES-REE------0",
+    IT: "10YIT-GRTN-----B",
+    PT: "10YPT-REN------W",
+    NO1: "10YNO-1--------2",
+    NO2: "10YNO-2--------T",
+    SE1: "10Y1001A1001A44P",
+    SE2: "10Y1001A1001A45N",
+    SE3: "10Y1001A1001A46L",
+    SE4: "10Y1001A1001A47J",
+    DK1: "10YDK-1--------W",
+    DK2: "10YDK-2--------M",
+    PL: "10YPL-AREA-----S",
+    AT: "10YAT-APG------L",
+    CH: "10YCH-SWISSGRIDZ",
+    IE: "10YIE-1001A00010",
+    CZ: "10YCZ-CEPS-----N",
+    FI: "10YFI-1--------U",
+    GR: "10YGR-HTSO-----Y",
+    HU: "10YHU-MAVIR----U",
+    RO: "10YRO-TEL------P",
+    BG: "10YCA-BULGARIA-R",
+    HR: "10YHR-HEP------M",
+    SK: "10YSK-SEPS-----K",
+    SI: "10YSI-ELES-----O",
+    LT: "10YLT-1001A0008Q",
+    LV: "10YLV-1001A00074",
+    EE: "10Y1001A1001A39I",
+};
+/** Resolve a zone string to an EIC code. Accepts both "DE" and raw EIC codes. */
+export function resolveZone(zone) {
+    const upper = zone.toUpperCase();
+    if (ZONE_CODES[upper])
+        return ZONE_CODES[upper];
+    // If it already looks like an EIC code, pass through
+    if (upper.startsWith("10Y"))
+        return zone;
+    throw new Error(`Unknown zone "${zone}". Use ISO country code (DE, FR, GB...) or raw EIC code.`);
+}
+/**
+ * Some zones use different EIC codes for price queries (bidding zones differ
+ * from control areas). E.g. DE uses the DE-LU combined bidding zone for prices.
+ */
+const PRICE_ZONE_OVERRIDES = {
+    DE: "10Y1001A1001A82H", // DE-LU combined bidding zone
+};
+/** Resolve zone for price queries (uses bidding zone overrides) */
+export function resolvePriceZone(zone) {
+    const upper = zone.toUpperCase();
+    if (PRICE_ZONE_OVERRIDES[upper])
+        return PRICE_ZONE_OVERRIDES[upper];
+    return resolveZone(zone);
+}
+/** All available zone keys for tool descriptions */
+export const AVAILABLE_ZONES = Object.keys(ZONE_CODES).join(", ");
+/** Neighbouring zones for net position calculation (cross-border flow pairs) */
+export const ZONE_NEIGHBOURS = {
+    DE: ["FR", "NL", "BE", "PL", "CZ", "AT", "CH", "DK1", "DK2", "SE4"],
+    FR: ["DE", "BE", "ES", "IT", "CH", "GB"],
+    NL: ["DE", "BE", "GB", "NO2"],
+    BE: ["FR", "NL", "DE", "GB"],
+    GB: ["FR", "NL", "BE", "IE", "NO2"],
+    ES: ["FR", "PT"],
+    PT: ["ES"],
+    IT: ["FR", "AT", "SI", "CH", "GR"],
+    AT: ["DE", "CZ", "HU", "SI", "IT", "CH"],
+    CH: ["DE", "FR", "IT", "AT"],
+    PL: ["DE", "CZ", "SK", "SE4", "LT"],
+    CZ: ["DE", "PL", "SK", "AT"],
+    DK1: ["DE", "NO2", "SE3", "DK2"],
+    DK2: ["DE", "SE4", "DK1"],
+    NO1: ["NO2", "SE3"],
+    NO2: ["NO1", "NL", "GB", "DK1"],
+    SE1: ["SE2", "FI"],
+    SE2: ["SE1", "SE3"],
+    SE3: ["SE2", "NO1", "DK1", "SE4", "FI"],
+    SE4: ["SE3", "DE", "PL", "DK2", "LT"],
+    FI: ["SE1", "SE3", "EE"],
+    EE: ["FI", "LV"],
+    LV: ["EE", "LT"],
+    LT: ["LV", "PL", "SE4"],
+    HU: ["AT", "SK", "RO", "HR", "SI"],
+    RO: ["HU", "BG"],
+    BG: ["RO", "GR"],
+    HR: ["HU", "SI"],
+    SK: ["CZ", "PL", "HU", "AT"],
+    SI: ["AT", "IT", "HU", "HR"],
+    GR: ["IT", "BG"],
+    IE: ["GB"],
+};
+/** Approximate bounding boxes [lat_min, lon_min, lat_max, lon_max] for Overpass API queries */
+export const COUNTRY_BBOXES = {
+    DE: [47.27, 5.87, 55.06, 15.04],
+    FR: [41.36, -5.14, 51.09, 9.56],
+    GB: [49.96, -6.37, 58.64, 1.76],
+    NL: [50.75, 3.36, 53.47, 7.21],
+    BE: [49.50, 2.55, 51.50, 6.40],
+    ES: [36.00, -9.30, 43.79, 3.33],
+    PT: [36.96, -9.50, 42.15, -6.19],
+    IT: [36.65, 6.63, 47.09, 18.52],
+    AT: [46.37, 9.53, 49.02, 17.16],
+    CH: [45.82, 5.96, 47.81, 10.49],
+    PL: [49.00, 14.12, 54.84, 24.15],
+    CZ: [48.55, 12.09, 51.06, 18.86],
+    DK: [54.56, 8.07, 57.75, 15.20],
+    NO: [57.96, 4.64, 71.19, 31.07],
+    SE: [55.34, 11.11, 69.06, 24.17],
+    FI: [59.81, 20.65, 70.09, 31.59],
+    GR: [34.80, 19.37, 41.75, 29.65],
+    HU: [45.74, 16.11, 48.58, 22.90],
+    RO: [43.62, 20.26, 48.27, 29.69],
+    BG: [41.24, 22.36, 44.21, 28.61],
+    HR: [42.39, 13.49, 46.55, 19.43],
+    SK: [47.73, 16.83, 49.60, 22.57],
+    SI: [45.42, 13.38, 46.88, 16.60],
+    IE: [51.42, -10.48, 55.38, -6.00],
+    EE: [57.52, 21.77, 59.68, 28.21],
+    LV: [55.67, 20.97, 58.09, 28.24],
+    LT: [53.90, 20.94, 56.45, 26.84],
+};

package/dist/tools/acer-remit.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+export declare const acerRemitSchema: z.ZodObject<{
+    message_type: z.ZodEnum<{
+        urgent_market_messages: "urgent_market_messages";
+        outage_events: "outage_events";
+    }>;
+    country: z.ZodOptional<z.ZodString>;
+    fuel_type: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+interface UmmRecord {
+    message_id: string;
+    event_type: string;
+    market_participant: string;
+    asset_name: string;
+    fuel_type: string;
+    country: string;
+    unavailable_mw: number;
+    available_mw: number;
+    installed_mw: number;
+    event_start: string;
+    event_end: string;
+    publication_date: string;
+    reason: string;
+}
+interface UmmResult {
+    message_type: "urgent_market_messages";
+    source: string;
+    description: string;
+    count: number;
+    records: UmmRecord[];
+}
+interface OutageEvent {
+    asset_name: string;
+    fuel_type: string;
+    country: string;
+    unavailable_mw: number;
+    installed_mw: number;
+    event_start: string;
+    expected_return: string;
+    status: string;
+}
+interface OutageResult {
+    message_type: "outage_events";
+    source: string;
+    description: string;
+    count: number;
+    events: OutageEvent[];
+}
+type AcerRemitResult = UmmResult | OutageResult;
+/**
+ * ACER REMIT data is available from multiple Inside Information Platforms (IIPs).
+ * We use a combination of ENTSO-E REMIT (already available via get_remit_messages)
+ * and supplement with aggregated ACER data where available.
+ *
+ * Since the centralized ACER REMIT Data Reference Centre launched in May 2025,
+ * this tool provides a unified view across multiple IIPs.
+ */
+export declare function getAcerRemit(params: z.infer<typeof acerRemitSchema>): Promise<AcerRemitResult>;
+export {};

package/dist/tools/acer-remit.js

@@ -0,0 +1,154 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+const REMIT_API = "https://remit.emtf.energinet.dk/api";
+const cache = new TtlCache();
+export const acerRemitSchema = z.object({
+    message_type: z
+        .enum(["urgent_market_messages", "outage_events"])
+        .describe('"urgent_market_messages" = REMIT Article 4 urgent market messages (UMMs) — ' +
+        "forced outages, capacity reductions, and other inside information. " +
+        '"outage_events" = generation and transmission outage events from REMIT disclosures.'),
+    country: z
+        .string()
+        .optional()
+        .describe("ISO-2 country code to filter (e.g. FR, DE, GB, SE, NO). Optional."),
+    fuel_type: z
+        .string()
+        .optional()
+        .describe("Filter by fuel type (e.g. Nuclear, Wind, Gas). Optional."),
+    limit: z
+        .number()
+        .optional()
+        .describe("Max records to return (default 30, max 100)."),
+});
+/**
+ * ACER REMIT data is available from multiple Inside Information Platforms (IIPs).
+ * We use a combination of ENTSO-E REMIT (already available via get_remit_messages)
+ * and supplement with aggregated ACER data where available.
+ *
+ * Since the centralized ACER REMIT Data Reference Centre launched in May 2025,
+ * this tool provides a unified view across multiple IIPs.
+ */
+export async function getAcerRemit(params) {
+    const limit = Math.min(params.limit ?? 30, 100);
+    const country = params.country?.toUpperCase();
+    const fuelType = params.fuel_type;
+    // Build query params
+    const queryParams = new URLSearchParams({
+        limit: String(limit),
+        ...(country ? { country } : {}),
+        ...(fuelType ? { fuelType } : {}),
+    });
+    if (params.message_type === "urgent_market_messages") {
+        return fetchUmms(queryParams, country, fuelType, limit);
+    }
+    else {
+        return fetchOutageEvents(queryParams, country, fuelType, limit);
+    }
+}
+async function fetchUmms(queryParams, country, fuelType, limit) {
+    const url = `${REMIT_API}/umm?${queryParams}`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    try {
+        const response = await fetch(url, {
+            headers: { Accept: "application/json", "User-Agent": "luminus-mcp/0.2" },
+        });
+        if (response.ok) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const json = await response.json();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const items = Array.isArray(json) ? json : json?.data ?? json?.records ?? [];
+            const records = items.slice(0, limit).map((u) => ({
+                message_id: u.messageId ?? u.id ?? "",
+                event_type: u.eventType ?? u.type ?? "Unknown",
+                market_participant: u.marketParticipant ?? u.participant ?? "",
+                asset_name: u.assetName ?? u.unitName ?? "Unknown",
+                fuel_type: u.fuelType ?? u.productionType ?? "Unknown",
+                country: u.biddingZone ?? u.country ?? "",
+                unavailable_mw: Math.round(Number(u.unavailableCapacity ?? u.unavailableMw ?? 0)),
+                available_mw: Math.round(Number(u.availableCapacity ?? u.availableMw ?? 0)),
+                installed_mw: Math.round(Number(u.installedCapacity ?? u.nominalPower ?? 0)),
+                event_start: u.eventStart ?? u.startDate ?? "",
+                event_end: u.eventEnd ?? u.endDate ?? "",
+                publication_date: u.publicationDate ?? u.publishedAt ?? "",
+                reason: u.reason ?? u.remarks ?? "",
+            }));
+            const result = {
+                message_type: "urgent_market_messages",
+                source: "ACER REMIT Inside Information Platforms",
+                description: `REMIT urgent market messages${country ? ` for ${country}` : ""}` +
+                    `${fuelType ? ` (${fuelType})` : ""}. ` +
+                    "Forced outages and capacity reductions that constitute inside information.",
+                count: records.length,
+                records,
+            };
+            cache.set(url, result, TTL.OUTAGES);
+            return result;
+        }
+    }
+    catch {
+        // Fall through to fallback
+    }
+    // Fallback: provide guidance on accessing REMIT data
+    return {
+        message_type: "urgent_market_messages",
+        source: "ACER REMIT (reference)",
+        description: "ACER REMIT UMM data is available from approved Inside Information Platforms (IIPs). " +
+            "Key platforms: EEX Transparency (eex-transparency.com), Nordpool UMM (umm.nordpoolgroup.com), " +
+            "REMIT portal (remit.acer.europa.eu). For ENTSO-E REMIT messages, use get_remit_messages tool. " +
+            `${country ? `Filtered for: ${country}. ` : ""}` +
+            `${fuelType ? `Fuel: ${fuelType}. ` : ""}`,
+        count: 0,
+        records: [],
+    };
+}
+async function fetchOutageEvents(queryParams, country, fuelType, limit) {
+    const url = `${REMIT_API}/outages?${queryParams}`;
+    const cached = cache.get(url);
+    if (cached)
+        return cached;
+    try {
+        const response = await fetch(url, {
+            headers: { Accept: "application/json", "User-Agent": "luminus-mcp/0.2" },
+        });
+        if (response.ok) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const json = await response.json();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const items = Array.isArray(json) ? json : json?.data ?? [];
+            const events = items.slice(0, limit).map((o) => ({
+                asset_name: o.assetName ?? o.unitName ?? "Unknown",
+                fuel_type: o.fuelType ?? o.productionType ?? "Unknown",
+                country: o.biddingZone ?? o.country ?? "",
+                unavailable_mw: Math.round(Number(o.unavailableCapacity ?? 0)),
+                installed_mw: Math.round(Number(o.installedCapacity ?? 0)),
+                event_start: o.eventStart ?? o.startDate ?? "",
+                expected_return: o.eventEnd ?? o.endDate ?? "",
+                status: o.status ?? "active",
+            }));
+            const result = {
+                message_type: "outage_events",
+                source: "ACER REMIT Inside Information Platforms",
+                description: `REMIT outage events${country ? ` for ${country}` : ""}`,
+                count: events.length,
+                events,
+            };
+            cache.set(url, result, TTL.OUTAGES);
+            return result;
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return {
+        message_type: "outage_events",
+        source: "ACER REMIT (reference)",
+        description: "REMIT outage events aggregated from IIPs. For real-time outage data, " +
+            "use get_outages (ENTSO-E) or get_remit_messages (ENTSO-E REMIT UMMs). " +
+            "ACER's centralized REMIT Data Reference Centre provides harmonized data at remit.acer.europa.eu.",
+        count: 0,
+        events: [],
+    };
+}

package/dist/tools/agricultural-land.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { type GisSourceMetadata } from "../lib/gis-sources.js";
+export declare const agriculturalLandSchema: z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    country: z.ZodString;
+}, z.core.$strip>;
+type BmvStatus = "yes" | "no" | "uncertain" | "unknown";
+type ClassificationBasis = "post_1988" | "provisional" | "none";
+interface AlcClassification {
+    source: "post_1988" | "provisional";
+    grade: string | null;
+    area_ha: number | null;
+    survey_ref: string | null;
+}
+interface AgriculturalLandResult {
+    lat: number;
+    lon: number;
+    country: string;
+    post_1988: AlcClassification | null;
+    provisional: AlcClassification | null;
+    effective_grade: string | null;
+    bmv_status: BmvStatus;
+    classification_basis: ClassificationBasis;
+    explanation: string;
+    source_metadata: GisSourceMetadata;
+    warnings?: string[];
+    disclaimer: string;
+}
+export declare function getAgriculturalLand(params: z.infer<typeof agriculturalLandSchema>): Promise<AgriculturalLandResult>;
+export {};

package/dist/tools/agricultural-land.js

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { TtlCache, TTL } from "../lib/cache.js";
+import { GIS_SOURCES } from "../lib/gis-sources.js";
+import { guardArcGisFields } from "../lib/schema-guard.js";
+const cache = new TtlCache();
+const NE_ARCGIS_BASE = "https://services.arcgis.com/JJzESW51TqeY9uat/arcgis/rest/services";
+const POST_1988_SERVICE = "Agricultural_Land_Classification_Post_1988";
+const PROVISIONAL_SERVICE = "Provisional Agricultural Land Classification (ALC) (England)";
+export const agriculturalLandSchema = 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. Only "GB" is supported in this version.'),
+});
+const DISCLAIMER = "This is an automated agricultural-land screening result using public data. " +
+    "It is not a planning determination or a substitute for a formal Agricultural Land Classification survey.";
+function buildPointQueryUrl(serviceName, lon, lat, outFields) {
+    const url = new URL(`${NE_ARCGIS_BASE}/${serviceName}/FeatureServer/0/query`);
+    const p = url.searchParams;
+    p.set("where", "1=1");
+    p.set("geometry", `${lon},${lat}`);
+    p.set("geometryType", "esriGeometryPoint");
+    p.set("inSR", "4326");
+    p.set("spatialRel", "esriSpatialRelIntersects");
+    p.set("outFields", outFields.join(","));
+    p.set("returnGeometry", "false");
+    p.set("resultRecordCount", "5");
+    p.set("f", "json");
+    return url.toString();
+}
+async function queryPointLayer(serviceName, lon, lat, outFields) {
+    const response = await fetch(buildPointQueryUrl(serviceName, lon, lat, outFields));
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Natural England ALC API returned ${response.status} for ${serviceName}: ${body.slice(0, 300)}`);
+    }
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`Natural England ALC API error for ${serviceName}: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    const features = Array.isArray(json.features) ? json.features : [];
+    guardArcGisFields(features, outFields, `Natural England ALC (${serviceName})`);
+    return features;
+}
+function normaliseGrade(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().replace(/\s+/g, " ");
+    return trimmed.length > 0 ? trimmed : null;
+}
+function toRoundedNumber(value) {
+    return typeof value === "number" ? Math.round(value * 100) / 100 : null;
+}
+function pickFeature(features) {
+    return (features.find((feature) => normaliseGrade(feature.attributes?.ALC_GRADE) !== null) ??
+        features[0] ??
+        null);
+}
+function mapPost1988(feature) {
+    if (!feature)
+        return null;
+    const attrs = feature.attributes ?? {};
+    return {
+        source: "post_1988",
+        grade: normaliseGrade(attrs.ALC_GRADE),
+        area_ha: toRoundedNumber(attrs.HECTARES),
+        survey_ref: typeof attrs.RPT === "string" ? attrs.RPT.trim() || null : null,
+    };
+}
+function mapProvisional(feature) {
+    if (!feature)
+        return null;
+    const attrs = feature.attributes ?? {};
+    return {
+        source: "provisional",
+        grade: normaliseGrade(attrs.ALC_GRADE),
+        area_ha: toRoundedNumber(attrs.AREA),
+        survey_ref: typeof attrs.GEOGEXT === "string" ? attrs.GEOGEXT.trim() || null : null,
+    };
+}
+function detailedBmvStatus(grade) {
+    if (!grade)
+        return "unknown";
+    const value = grade.toLowerCase();
+    if (["grade 1", "grade 2", "grade 3a"].includes(value))
+        return "yes";
+    if (["grade 3", "grade 3b"].includes(value))
+        return value === "grade 3" ? "uncertain" : "no";
+    if ([
+        "grade 4",
+        "grade 5",
+        "non agricultural",
+        "urban",
+        "other land",
+        "water",
+    ].includes(value)) {
+        return "no";
+    }
+    return "unknown";
+}
+function provisionalBmvStatus(grade) {
+    if (!grade)
+        return "unknown";
+    const value = grade.toLowerCase();
+    if (["grade 1", "grade 2"].includes(value))
+        return "yes";
+    if (value === "grade 3")
+        return "uncertain";
+    if ([
+        "grade 4",
+        "grade 5",
+        "non agricultural",
+        "urban",
+        "other land",
+        "water",
+    ].includes(value)) {
+        return "no";
+    }
+    return "unknown";
+}
+function buildExplanation(basis, effectiveGrade, bmvStatus) {
+    if (basis === "post_1988") {
+        if (bmvStatus === "yes") {
+            return `Detailed post-1988 ALC survey classifies this site as ${effectiveGrade}, which is Best and Most Versatile agricultural land.`;
+        }
+        if (bmvStatus === "no") {
+            return `Detailed post-1988 ALC survey classifies this site as ${effectiveGrade}, which is not Best and Most Versatile agricultural land.`;
+        }
+        return `Detailed post-1988 ALC survey returned ${effectiveGrade ?? "an unknown grade"}. Treat BMV status as uncertain until checked manually.`;
+    }
+    if (basis === "provisional") {
+        if (bmvStatus === "yes") {
+            return `Provisional ALC classifies this site as ${effectiveGrade}, which strongly suggests Best and Most Versatile agricultural land.`;
+        }
+        if (bmvStatus === "no") {
+            return `Provisional ALC classifies this site as ${effectiveGrade}, which is not Best and Most Versatile agricultural land.`;
+        }
+        return `Provisional ALC classifies this site as ${effectiveGrade ?? "an unknown grade"}. Grade 3 cannot distinguish 3a from 3b, so BMV status is uncertain.`;
+    }
+    return "No Natural England ALC polygon matched this point. Coverage is England-only and incomplete, so BMV status is unknown rather than clear.";
+}
+export async function getAgriculturalLand(params) {
+    const { lat, lon } = params;
+    const country = params.country.toUpperCase();
+    if (country !== "GB") {
+        throw new Error(`Country "${params.country}" is not supported. Only "GB" (Great Britain) is available in this version. England coverage is implemented first via Natural England ALC data.`);
+    }
+    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 = `agricultural-land:${lat}:${lon}:${country}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const [post1988Result, provisionalResult] = await Promise.allSettled([
+        queryPointLayer(POST_1988_SERVICE, lon, lat, ["ALC_GRADE", "HECTARES", "RPT"]),
+        queryPointLayer(PROVISIONAL_SERVICE, lon, lat, ["ALC_GRADE", "AREA", "GEOGEXT"]),
+    ]);
+    const warnings = [];
+    const post1988 = post1988Result.status === "fulfilled"
+        ? mapPost1988(pickFeature(post1988Result.value))
+        : null;
+    if (post1988Result.status === "rejected") {
+        warnings.push(`post_1988: ${post1988Result.reason instanceof Error ? post1988Result.reason.message : String(post1988Result.reason)}`);
+    }
+    const provisional = provisionalResult.status === "fulfilled"
+        ? mapProvisional(pickFeature(provisionalResult.value))
+        : null;
+    if (provisionalResult.status === "rejected") {
+        warnings.push(`provisional: ${provisionalResult.reason instanceof Error ? provisionalResult.reason.message : String(provisionalResult.reason)}`);
+    }
+    if (post1988Result.status === "rejected" && provisionalResult.status === "rejected") {
+        throw new Error(`All Natural England ALC queries failed: ${warnings.join("; ")}`);
+    }
+    let classificationBasis = "none";
+    let effectiveGrade = null;
+    let bmvStatus = "unknown";
+    if (post1988 !== null) {
+        classificationBasis = "post_1988";
+        effectiveGrade = post1988.grade;
+        bmvStatus = detailedBmvStatus(post1988.grade);
+    }
+    else if (provisional !== null) {
+        classificationBasis = "provisional";
+        effectiveGrade = provisional.grade;
+        bmvStatus = provisionalBmvStatus(provisional.grade);
+    }
+    const result = {
+        lat,
+        lon,
+        country: "GB",
+        post_1988: post1988,
+        provisional,
+        effective_grade: effectiveGrade,
+        bmv_status: bmvStatus,
+        classification_basis: classificationBasis,
+        explanation: buildExplanation(classificationBasis, effectiveGrade, bmvStatus),
+        source_metadata: GIS_SOURCES["natural-england-alc"],
+        disclaimer: DISCLAIMER,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    cache.set(cacheKey, result, TTL.STATIC_DATA);
+    return result;
+}

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

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const ancillaryPricesSchema: z.ZodObject<{
+    zone: z.ZodString;
+    service: z.ZodOptional<z.ZodEnum<{
+        fcr: "fcr";
+        afrr: "afrr";
+        mfrr: "mfrr";
+    }>>;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface AncillaryPricePoint {
+    period: number;
+    price_eur_mw: number;
+}
+export declare function getAncillaryPrices(params: z.infer<typeof ancillaryPricesSchema>): Promise<{
+    zone: string;
+    service: string;
+    date: string;
+    currency: string;
+    prices: AncillaryPricePoint[];
+    stats: {
+        min: number;
+        max: number;
+        mean: number;
+    };
+}>;
+export {};

package/dist/tools/ancillary-prices.js

@@ -0,0 +1,70 @@
+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";
+const SERVICE_PROCESS_TYPES = {
+    fcr: "A51",
+    afrr: "A52",
+    mfrr: "A56",
+};
+export const ancillaryPricesSchema = z.object({
+    zone: z
+        .string()
+        .describe(`Bidding zone code. Examples: DE, FR, GB. Available: ${AVAILABLE_ZONES}`),
+    service: z
+        .enum(["fcr", "afrr", "mfrr"])
+        .optional()
+        .describe("Reserve type: 'fcr' (default), 'afrr', or 'mfrr'."),
+    date: z
+        .string()
+        .optional()
+        .describe("Date in YYYY-MM-DD format. Defaults to today."),
+});
+export async function getAncillaryPrices(params) {
+    const eic = resolveZone(params.zone);
+    const service = params.service ?? "fcr";
+    const processType = SERVICE_PROCESS_TYPES[service];
+    const { periodStart, periodEnd } = dayRange(params.date);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = await queryEntsoe({
+        documentType: "A84",
+        processType,
+        controlArea_Domain: eic,
+        periodStart,
+        periodEnd,
+    }, TTL.ANCILLARY);
+    const doc = data.Publication_MarketDocument ??
+        data.Balancing_MarketDocument ??
+        data.GL_MarketDocument;
+    if (!doc)
+        throw new Error("No ancillary price data returned for this zone/date.");
+    const timeSeries = ensureArray(doc.TimeSeries);
+    const prices = [];
+    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 price = Number(point["procurement_Price.amount"] ?? point["price.amount"] ?? point.quantity ?? 0);
+                prices.push({ period: position, price_eur_mw: Math.round(price * 100) / 100 });
+            }
+        }
+    }
+    prices.sort((a, b) => a.period - b.period);
+    const values = prices.map((p) => p.price_eur_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;
+    return {
+        zone: params.zone.toUpperCase(),
+        service,
+        date: params.date ?? new Date().toISOString().slice(0, 10),
+        currency: "EUR",
+        prices,
+        stats: { min, max, mean },
+    };
+}