@cyanheads/eia-energy-mcp-server 0.2.0

package/dist/mcp-server/tools/definitions/describe-route.tool.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Tool definition for eia_describe_route. Returns full metadata
+ * for a leaf route: facets with valid values, data columns, frequencies, units,
+ * and date range. Required reading before constructing filters for eia_query_route.
+ * Facet values are fetched from separate /facet/{id} endpoints and merged.
+ * @module mcp-server/tools/definitions/describe-route.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEiaApiService } from '../../../services/eia/eia-service.js';
+export const describeRouteTool = tool('eia_describe_route', {
+    title: 'Describe EIA Route',
+    description: 'Returns full metadata for a leaf route: available facets with their valid values, data column names and units, frequency options, and date range. Call this before eia_query_route to discover valid facet IDs, facet values, column IDs, and frequency codes. Facet values are fetched from separate EIA endpoints and merged — results are cached per-route for the process lifetime to minimize API calls.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    input: z.object({
+        route: z
+            .string()
+            .min(1)
+            .describe('Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes.'),
+    }),
+    output: z.object({
+        route: z.string().describe('The route path described.'),
+        description: z.string().describe('Human-readable description of the dataset.'),
+        facets: z
+            .array(z
+            .object({
+            id: z
+                .string()
+                .describe('Facet ID — use as key in the filters parameter of eia_query_route (e.g. filters: { "stateid": "TX" }).'),
+            description: z.string().describe('Facet description.'),
+            values: z
+                .array(z
+                .object({
+                id: z.string().describe('Facet value ID — use as filter value.'),
+                name: z.string().describe('Human-readable name.'),
+                alias: z.string().optional().describe('Short alias, when provided by EIA.'),
+            })
+                .describe('A valid facet value.'))
+                .describe('Valid values for this facet dimension.'),
+        })
+            .describe('A filterable dimension for this route.'))
+            .describe('Filterable dimensions. Each facet has an ID and a set of valid values.'),
+        data_columns: z
+            .array(z
+            .object({
+            id: z.string().describe('Column ID — use in the columns parameter of eia_query_route.'),
+            alias: z.string().describe('Human-readable column alias.'),
+            units: z.string().describe('Measurement units (e.g. "cents per kilowatt-hour").'),
+        })
+            .describe('A data column available for this route.'))
+            .describe('Data columns available for this route.'),
+        frequencies: z
+            .array(z
+            .object({
+            id: z.string().describe('Frequency ID (e.g. "monthly", "annual").'),
+            description: z.string().describe('Human-readable description.'),
+            query: z.string().describe('API query value for this frequency.'),
+            format: z.string().describe('Period format string (e.g. "YYYY-MM", "YYYY").'),
+        })
+            .describe('A frequency option for eia_query_route.'))
+            .describe('Valid frequency options for eia_query_route.'),
+        date_range: z
+            .object({
+            start: z.string().describe('Earliest available period.'),
+            end: z.string().describe('Latest available period.'),
+        })
+            .describe('Available date range for this route.'),
+        default_frequency: z.string().describe('Default frequency ID used when none is specified.'),
+        default_date_format: z
+            .string()
+            .describe('Period format for the default frequency (e.g. "YYYY-MM").'),
+    }),
+    errors: [
+        {
+            reason: 'route_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Route does not exist in the EIA taxonomy.',
+            recovery: 'Use eia_browse_routes or eia_search_routes to discover valid leaf route paths.',
+        },
+        {
+            reason: 'route_not_queryable',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Route is a category node with sub-routes, not a queryable leaf.',
+            recovery: 'Use eia_browse_routes to drill into sub-routes, or eia_search_routes to find leaf routes.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            retryable: true,
+            when: 'EIA rate limit hit during facet fan-out.',
+            recovery: 'Back off and retry; use a production EIA API key for higher rate limits.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Executing eia_describe_route', { route: input.route });
+        const service = getEiaApiService();
+        const meta = await service.describe(input.route, ctx);
+        return {
+            route: meta.route,
+            description: meta.description,
+            facets: meta.facets.map((f) => ({
+                id: f.id,
+                description: f.description,
+                values: f.values.map((v) => ({
+                    id: v.id,
+                    name: v.name,
+                    ...(v.alias !== undefined && { alias: v.alias }),
+                })),
+            })),
+            data_columns: meta.dataColumns.map((c) => ({
+                id: c.id,
+                alias: c.alias,
+                units: c.units,
+            })),
+            frequencies: meta.frequencies.map((freq) => ({
+                id: freq.id,
+                description: freq.description,
+                query: freq.query,
+                format: freq.format,
+            })),
+            date_range: {
+                start: meta.dateRange.start,
+                end: meta.dateRange.end,
+            },
+            default_frequency: meta.defaultFrequency,
+            default_date_format: meta.defaultDateFormat,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## ${result.route}`);
+        if (result.description)
+            lines.push(`\n${result.description}\n`);
+        lines.push(`**Date range:** ${result.date_range.start} → ${result.date_range.end}`);
+        lines.push(`**Default frequency:** ${result.default_frequency} (format: ${result.default_date_format})\n`);
+        if (result.data_columns.length) {
+            lines.push('### Data columns');
+            for (const col of result.data_columns) {
+                lines.push(`- **${col.id}** (${col.alias}) — ${col.units}`);
+            }
+            lines.push('');
+        }
+        if (result.frequencies.length) {
+            lines.push('### Frequencies');
+            for (const freq of result.frequencies) {
+                lines.push(`- **${freq.id}** (query: ${freq.query}) — ${freq.description} (format: ${freq.format})`);
+            }
+            lines.push('');
+        }
+        if (result.facets.length) {
+            lines.push('### Facets (filter dimensions)');
+            for (const facet of result.facets) {
+                const preview = facet.values.slice(0, 5);
+                const more = facet.values.length > 5 ? ` (+${facet.values.length - 5} more)` : '';
+                const valueList = preview
+                    .map((v) => (v.alias ? `${v.id}=${v.name} (${v.alias})` : `${v.id}=${v.name}`))
+                    .join(', ');
+                lines.push(`- **${facet.id}**: ${facet.description} — ${valueList}${more}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=describe-route.tool.js.map

package/dist/mcp-server/tools/definitions/describe-route.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-route.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe-route.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/query-route.tool.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Tool definition for eia_query_route. Fetches data from a leaf
+ * route with optional facet filters, date range, frequency, and column
+ * selection. Data values come back as strings per the EIA API. Large result
+ * sets spill to a DataCanvas table (when CANVAS_PROVIDER_TYPE=duckdb) and
+ * return a canvas_id + dataset handle for SQL analysis via eia_dataframe_query.
+ * @module mcp-server/tools/definitions/query-route.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const queryRouteTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    route: z.ZodString;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    frequency: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodString>;
+    end: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>>>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    length: z.ZodDefault<z.ZodNumber>;
+    canvas_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    route: z.ZodString;
+    data: z.ZodArray<z.ZodObject<{}, z.core.$loose>>;
+    total: z.ZodNumber;
+    returned_count: z.ZodNumber;
+    frequency: z.ZodString;
+    date_format: z.ZodString;
+    canvas_id: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodOptional<z.ZodString>;
+    canvas_preview_note: z.ZodOptional<z.ZodString>;
+    truncation_warning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "route_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Route does not exist or is not a leaf.";
+    readonly recovery: "Use eia_browse_routes or eia_search_routes to find a valid leaf route path.";
+}, {
+    readonly reason: "invalid_facet";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "An unknown facet key was used in filters.";
+    readonly recovery: "Call eia_describe_route to see valid facet IDs for this route.";
+}, {
+    readonly reason: "no_data";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Route exists but filters yield zero rows.";
+    readonly recovery: "Broaden filters, remove date constraints, or call eia_describe_route to verify facet values — an invalid facet value silently returns zero rows.";
+}, {
+    readonly reason: "length_exceeded";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "length parameter exceeds the EIA maximum of 5000.";
+    readonly recovery: "Reduce length to 5000 or use offset pagination for larger result sets.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly retryable: true;
+    readonly when: "EIA rate limit hit (OVER_RATE_LIMIT).";
+    readonly recovery: "Back off and retry; use a production EIA API key for higher rate limits.";
+}]>;
+//# sourceMappingURL=query-route.tool.d.ts.map

package/dist/mcp-server/tools/definitions/query-route.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-route.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/query-route.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgUzB,CAAC"}

package/dist/mcp-server/tools/definitions/query-route.tool.js

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Tool definition for eia_query_route. Fetches data from a leaf
+ * route with optional facet filters, date range, frequency, and column
+ * selection. Data values come back as strings per the EIA API. Large result
+ * sets spill to a DataCanvas table (when CANVAS_PROVIDER_TYPE=duckdb) and
+ * return a canvas_id + dataset handle for SQL analysis via eia_dataframe_query.
+ * @module mcp-server/tools/definitions/query-route.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/canvas-bridge.js';
+import { getEiaApiService } from '../../../services/eia/eia-service.js';
+export const queryRouteTool = tool('eia_query_route', {
+    title: 'Query EIA Route Data',
+    description: 'Fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. Use eia_describe_route first to discover valid facet IDs, facet values, column IDs, and frequency codes. Data values are strings in the response (EIA API returns all numeric values as strings, e.g. "9.13"); cast to DOUBLE in SQL when arithmetic is needed. Returns a preview inline; large result sets (total > length) spill to a DataCanvas table when canvas is enabled — use the returned canvas_id and dataset name with eia_dataframe_query for SQL analysis. Pass the same canvas_id on subsequent eia_query_route calls to accumulate multiple route results into one canvas for cross-route joins.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    input: z.object({
+        route: z
+            .string()
+            .min(1)
+            .describe('Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes.'),
+        filters: z
+            .record(z.string(), z.union([z.string(), z.array(z.string())]))
+            .optional()
+            .describe('Facet filters keyed by facet ID (e.g. { "stateid": "TX", "sectorid": ["RES", "COM"] }). Use the facets[].id values returned by eia_describe_route as keys here.'),
+        columns: z
+            .array(z.string())
+            .optional()
+            .describe('Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.'),
+        frequency: z
+            .string()
+            .optional()
+            .describe('Aggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route.'),
+        start: z
+            .string()
+            .optional()
+            .describe('Period start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route.'),
+        end: z.string().optional().describe('Period end (same format as start).'),
+        sort: z
+            .array(z
+            .object({
+            column: z.string().describe('Column ID to sort by.'),
+            direction: z.enum(['asc', 'desc']).describe('Sort direction.'),
+        })
+            .describe('A sort criterion.'))
+            .optional()
+            .describe('Result ordering.'),
+        offset: z.number().int().min(0).default(0).describe('Pagination offset (default 0).'),
+        length: z
+            .number()
+            .int()
+            .min(1)
+            .max(5000)
+            .default(100)
+            .describe('Rows to fetch per request (default 100, max 5000 per EIA limit).'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('DataCanvas ID to register results into. Omit on first call — a new canvas is minted and returned. Pass the returned canvas_id on subsequent calls to accumulate multiple route results into one canvas for cross-route SQL joins.'),
+    }),
+    output: z.object({
+        route: z.string().describe('The route path queried.'),
+        data: z
+            .array(z.object({}).passthrough().describe('A single data row with dynamic column keys.'))
+            .describe('Preview rows. All numeric values are strings per the EIA API (e.g. "9.13"). Cast to DOUBLE in SQL for arithmetic: CAST(value AS DOUBLE). Per-column units appear as {col}-units fields inline in each row. Keys are dynamic column IDs from the EIA route.'),
+        total: z.number().describe('Total matching rows in the EIA dataset.'),
+        returned_count: z
+            .number()
+            .describe('Rows in this response. When returned_count < total, use offset or canvas for the rest.'),
+        frequency: z.string().describe('Frequency of the returned data.'),
+        date_format: z.string().describe('Period format for the returned data (e.g. "YYYY-MM").'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('Canvas workspace ID — present when spillover occurred or canvas_id was supplied. Pass to subsequent eia_query_route calls to accumulate datasets.'),
+        dataset: z
+            .string()
+            .optional()
+            .describe('df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>).'),
+        canvas_preview_note: z
+            .string()
+            .optional()
+            .describe('Human-readable note when total > returned rows, describing how to access the full dataset via canvas SQL.'),
+        truncation_warning: z
+            .string()
+            .optional()
+            .describe("Forwarded from EIA's warnings[] when the API warns of truncated results near the 5,000 per-page limit."),
+    }),
+    errors: [
+        {
+            reason: 'route_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Route does not exist or is not a leaf.',
+            recovery: 'Use eia_browse_routes or eia_search_routes to find a valid leaf route path.',
+        },
+        {
+            reason: 'invalid_facet',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'An unknown facet key was used in filters.',
+            recovery: 'Call eia_describe_route to see valid facet IDs for this route.',
+        },
+        {
+            reason: 'no_data',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Route exists but filters yield zero rows.',
+            recovery: 'Broaden filters, remove date constraints, or call eia_describe_route to verify facet values — an invalid facet value silently returns zero rows.',
+        },
+        {
+            reason: 'length_exceeded',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'length parameter exceeds the EIA maximum of 5000.',
+            recovery: 'Reduce length to 5000 or use offset pagination for larger result sets.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            retryable: true,
+            when: 'EIA rate limit hit (OVER_RATE_LIMIT).',
+            recovery: 'Back off and retry; use a production EIA API key for higher rate limits.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Executing eia_query_route', {
+            route: input.route,
+            offset: input.offset,
+            length: input.length,
+        });
+        // Pre-flight: detect inverted date range before hitting the EIA API.
+        // ISO date strings (YYYY-MM, YYYY-MM-DD, YYYY) sort lexicographically, so
+        // string comparison is sufficient for this check.
+        if (input.start !== undefined && input.end !== undefined && input.start > input.end) {
+            throw ctx.fail('no_data', `Date range is inverted: start "${input.start}" is after end "${input.end}". Swap start and end to retrieve data.`, {
+                route: input.route,
+                start: input.start,
+                end: input.end,
+                ...ctx.recoveryFor('no_data'),
+            });
+        }
+        const service = getEiaApiService();
+        const dataResp = await service.query(input.route, {
+            ...(input.filters !== undefined && { filters: input.filters }),
+            ...(input.columns !== undefined && { columns: input.columns }),
+            ...(input.frequency !== undefined && { frequency: input.frequency }),
+            ...(input.start !== undefined && { start: input.start }),
+            ...(input.end !== undefined && { end: input.end }),
+            ...(input.sort !== undefined && { sort: input.sort }),
+            offset: input.offset,
+            length: input.length,
+        }, ctx);
+        if (dataResp.total === 0 && dataResp.data.length === 0) {
+            throw ctx.fail('no_data', `Route "${input.route}" returned zero rows for the given filters.`, {
+                route: input.route,
+                ...ctx.recoveryFor('no_data'),
+            });
+        }
+        const result = {
+            route: input.route,
+            data: dataResp.data,
+            total: dataResp.total,
+            returned_count: dataResp.data.length,
+            frequency: dataResp.frequency,
+            date_format: dataResp.dateFormat,
+        };
+        // Forward EIA server-side truncation warnings
+        if (dataResp.warnings?.length) {
+            result.truncation_warning = dataResp.warnings.join('; ');
+        }
+        // DataCanvas spillover — opt-in via CANVAS_PROVIDER_TYPE=duckdb
+        const bridge = getCanvasBridge();
+        if (bridge && dataResp.data.length > 0) {
+            const registered = await bridge.registerDataframe(ctx, {
+                rows: dataResp.data,
+                sourceTool: 'eia_query_route',
+                queryParams: {
+                    route: input.route,
+                    filters: input.filters,
+                    columns: input.columns,
+                    frequency: input.frequency,
+                    start: input.start,
+                    end: input.end,
+                    offset: input.offset,
+                    length: input.length,
+                },
+                truncated: dataResp.total > dataResp.data.length,
+                maxRows: input.length,
+            });
+            if (registered) {
+                result.dataset = registered.tableName;
+                // Acquire or reuse canvas ID
+                if (input.canvas_id) {
+                    result.canvas_id = input.canvas_id;
+                }
+                else {
+                    // The bridge manages the canvas internally; surface a stable per-tenant ID
+                    // by using the bridge's shared canvas. We mint the canvas_id from the
+                    // dataset name prefix for consistency.
+                    result.canvas_id = registered.tableName;
+                }
+                if (dataResp.total > dataResp.data.length) {
+                    result.canvas_preview_note = `Showing ${dataResp.data.length.toLocaleString()} of ${dataResp.total.toLocaleString()} rows — query canvas for full dataset using: SELECT * FROM ${registered.tableName}`;
+                }
+            }
+        }
+        else if (dataResp.total > dataResp.data.length) {
+            result.canvas_preview_note = `Showing ${dataResp.data.length.toLocaleString()} of ${dataResp.total.toLocaleString()} rows — enable DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) for full dataset access, or use offset pagination.`;
+        }
+        return result;
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## Query: ${result.route}`);
+        lines.push(`**Frequency:** ${result.frequency} | **Date format:** ${result.date_format}`);
+        lines.push(`**Rows:** ${result.returned_count} of ${result.total} total\n`);
+        if (result.canvas_preview_note) {
+            lines.push(`> ${result.canvas_preview_note}\n`);
+        }
+        if (result.dataset) {
+            lines.push(`**Dataset:** \`${result.dataset}\` (canvas: ${result.canvas_id})`);
+            lines.push('Use `eia_dataframe_query` with this dataset name for full SQL access.\n');
+        }
+        if (result.truncation_warning) {
+            lines.push(`> **Warning:** ${result.truncation_warning}\n`);
+        }
+        if (result.data.length === 0) {
+            lines.push('_No rows returned._');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        // Render table — separate data columns from {col}-units columns.
+        // Units are identical on every row, so annotate the header instead of
+        // repeating them in the body.
+        const firstRow = result.data[0];
+        if (!firstRow)
+            return [{ type: 'text', text: lines.join('\n') }];
+        const allKeys = Object.keys(firstRow);
+        // Build a units map from the first row: { colName: "unit string" }
+        const unitsMap = {};
+        for (const key of allKeys) {
+            if (key.endsWith('-units')) {
+                const col = key.slice(0, -6); // strip trailing '-units'
+                const unit = firstRow[key];
+                if (unit !== null && unit !== undefined)
+                    unitsMap[col] = String(unit);
+            }
+        }
+        // Data columns are all keys that are not {col}-units entries
+        const dataCols = allKeys.filter((k) => !k.endsWith('-units'));
+        // Header: "col (unit)" when a unit is known, else just "col"
+        const headerCells = dataCols.map((c) => (unitsMap[c] ? `${c} (${unitsMap[c]})` : c));
+        const header = `| ${headerCells.join(' | ')} |`;
+        const sep = `| ${dataCols.map(() => '---').join(' | ')} |`;
+        lines.push(header, sep);
+        for (const row of result.data) {
+            const cells = dataCols.map((c) => {
+                const v = row[c];
+                if (v === null || v === undefined)
+                    return '';
+                return String(v).replace(/\|/g, '\\|');
+            });
+            lines.push(`| ${cells.join(' | ')} |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=query-route.tool.js.map

package/dist/mcp-server/tools/definitions/query-route.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-route.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/query-route.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search-routes.tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Tool definition for eia_search_routes. Fuzzy text search across
+ * route names, descriptions, and category labels using an in-memory Fuse.js
+ * index. Resolves natural-language queries to route paths. STEO series names
+ * (1,469 entries) are included in the index for series discovery.
+ * @module mcp-server/tools/definitions/search-routes.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const searchRoutesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        route: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        score: z.ZodNumber;
+        isLeaf: z.ZodBoolean;
+        filter_hint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    total_indexed: z.ZodNumber;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=search-routes.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-routes.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-routes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-routes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;6BAmG3B,CAAC"}

package/dist/mcp-server/tools/definitions/search-routes.tool.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Tool definition for eia_search_routes. Fuzzy text search across
+ * route names, descriptions, and category labels using an in-memory Fuse.js
+ * index. Resolves natural-language queries to route paths. STEO series names
+ * (1,469 entries) are included in the index for series discovery.
+ * @module mcp-server/tools/definitions/search-routes.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getEiaApiService } from '../../../services/eia/eia-service.js';
+export const searchRoutesTool = tool('eia_search_routes', {
+    title: 'Search EIA Routes',
+    description: 'Fuzzy text search across route names, descriptions, and category labels. Resolves natural-language queries like "electricity retail sales by state" or "natural gas imports" to matching route paths. STEO series names are indexed so queries like "ethanol net imports" or "crude oil production forecast" also resolve. Results include isLeaf so you know whether to browse further or query directly. Results with score > 0.5 are weak matches — try a more specific query or use eia_browse_routes to explore the taxonomy.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Free-text search terms to match against route names and descriptions.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(30)
+            .default(10)
+            .describe('Maximum results to return (default 10, max 30).'),
+    }),
+    output: z.object({
+        results: z
+            .array(z
+            .object({
+            route: z
+                .string()
+                .describe('Route path — usable directly in eia_describe_route or eia_query_route.'),
+            name: z.string().describe('Human-readable route name.'),
+            description: z.string().describe('Route description.'),
+            score: z
+                .number()
+                .describe('Fuzzy match score: 0 = exact, 1 = no match. Lower is better.'),
+            isLeaf: z
+                .boolean()
+                .describe('True when the route is a queryable leaf; false when it has sub-routes to browse.'),
+            filter_hint: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Pre-built filter for eia_query_route when a specific facet value is required. Present on STEO series results — pass directly as filters (e.g. eia_query_route(route="steo", filters=filter_hint)).'),
+        })
+            .describe('A search result entry.'))
+            .describe('Ranked matches, best first.'),
+        total_indexed: z
+            .number()
+            .describe('Total entries in the search index (routes + STEO series names).'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('Executing eia_search_routes', { query: input.query, limit: input.limit });
+        const service = getEiaApiService();
+        const { results, totalIndexed } = await service.search(input.query, input.limit, ctx);
+        return {
+            results: results.map(({ entry, score }) => ({
+                route: entry.route,
+                name: entry.name,
+                description: entry.description,
+                score,
+                isLeaf: entry.isLeaf,
+                ...(entry.filter_hint !== undefined && { filter_hint: entry.filter_hint }),
+            })),
+            total_indexed: totalIndexed,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        if (result.results.length === 0) {
+            lines.push('No matching routes found. Try different search terms or browse with eia_browse_routes.');
+            lines.push(`\nIndex size: ${result.total_indexed} entries`);
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        lines.push(`**${result.results.length} result(s)** (index: ${result.total_indexed} entries)\n`);
+        for (const r of result.results) {
+            const tag = r.isLeaf ? '[leaf]' : '[cat]';
+            const weakMatch = r.score > 0.5 ? ' ⚠ weak match' : '';
+            lines.push(`${tag} **${r.route}** (score: ${r.score.toFixed(3)}${weakMatch})`);
+            lines.push(`  ${r.name}`);
+            if (r.description)
+                lines.push(`  ${r.description}`);
+            if (r.filter_hint) {
+                const hint = Object.entries(r.filter_hint)
+                    .map(([k, v]) => `"${k}": "${v}"`)
+                    .join(', ');
+                lines.push(`  Query with: \`eia_query_route(route="${r.route}", filters={${hint}})\``);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=search-routes.tool.js.map