@cyanheads/eia-energy-mcp-server 0.2.0

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview eia-energy-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp, disabledTool } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from './config/server-config.js';
+import { browseRoutesTool } from './mcp-server/tools/definitions/browse-routes.tool.js';
+import { dataframeDescribeTool } from './mcp-server/tools/definitions/dataframe-describe.tool.js';
+import { dataframeDropTool } from './mcp-server/tools/definitions/dataframe-drop.tool.js';
+import { dataframeQueryTool } from './mcp-server/tools/definitions/dataframe-query.tool.js';
+import { describeRouteTool } from './mcp-server/tools/definitions/describe-route.tool.js';
+import { queryRouteTool } from './mcp-server/tools/definitions/query-route.tool.js';
+import { searchRoutesTool } from './mcp-server/tools/definitions/search-routes.tool.js';
+import { initCanvasBridge } from './services/canvas-bridge/canvas-bridge.js';
+import { initEiaApiService } from './services/eia/eia-service.js';
+const serverConfig = getServerConfig();
+const dropTool = serverConfig.dataframeDropEnabled
+    ? dataframeDropTool
+    : disabledTool(dataframeDropTool, {
+        reason: 'Dataframe drop is disabled in this deployment.',
+        hint: 'EIA_DATAFRAME_DROP_ENABLED=true',
+    });
+await createApp({
+    tools: [
+        browseRoutesTool,
+        describeRouteTool,
+        searchRoutesTool,
+        queryRouteTool,
+        dataframeDescribeTool,
+        dataframeQueryTool,
+        dropTool,
+    ],
+    setup(core) {
+        initEiaApiService();
+        initCanvasBridge(core.canvas);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sDAAsD,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2DAA2D,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sDAAsD,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC,MAAM,QAAQ,GAAG,YAAY,CAAC,oBAAoB;IAChD,CAAC,CAAC,iBAAiB;IACnB,CAAC,CAAC,YAAY,CAAC,iBAAiB,EAAE;QAC9B,MAAM,EAAE,gDAAgD;QACxD,IAAI,EAAE,iCAAiC;KACxC,CAAC,CAAC;AAEP,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,gBAAgB;QAChB,iBAAiB;QACjB,gBAAgB;QAChB,cAAc;QACd,qBAAqB;QACrB,kBAAkB;QAClB,QAAQ;KACT;IACD,KAAK,CAAC,IAAI;QACR,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Tool definition for eia_browse_routes. Lists child routes under
+ * a given path in the EIA dataset taxonomy. Start at root (omit path) to see
+ * the 14 top-level categories, then drill into subcategories until reaching
+ * leaf routes that can be queried with eia_query_route.
+ * @module mcp-server/tools/definitions/browse-routes.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const browseRoutesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    children: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        route: z.ZodString;
+        isLeaf: z.ZodBoolean;
+    }, z.core.$strip>>;
+    isLeaf: z.ZodBoolean;
+}, z.core.$strip>, readonly [{
+    readonly reason: "route_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Path does not exist in the EIA taxonomy.";
+    readonly recovery: "Call eia_browse_routes without a path to see valid top-level categories.";
+}]>;
+//# sourceMappingURL=browse-routes.tool.d.ts.map

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

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

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

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Tool definition for eia_browse_routes. Lists child routes under
+ * a given path in the EIA dataset taxonomy. Start at root (omit path) to see
+ * the 14 top-level categories, then drill into subcategories until reaching
+ * leaf routes that can be queried with eia_query_route.
+ * @module mcp-server/tools/definitions/browse-routes.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 browseRoutesTool = tool('eia_browse_routes', {
+    title: 'Browse EIA Routes',
+    description: 'Lists child routes under a given path in the EIA dataset taxonomy. Start with no path to get the 14 top-level categories (electricity, petroleum, natural-gas, steo, aeo, ieo, seds, etc.), then drill into subcategories. Each result includes an isLeaf flag — leaf routes are queryable endpoints; non-leaf routes have children to browse. When isLeaf is true on the browsed path itself, switch to eia_describe_route.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    input: z.object({
+        path: z
+            .string()
+            .optional()
+            .describe('Route path to browse (e.g. "electricity", "petroleum/pri"). Omit for root.'),
+    }),
+    output: z.object({
+        path: z.string().describe('The path that was browsed (empty string for root).'),
+        children: z
+            .array(z
+            .object({
+            id: z.string().describe('Route segment ID.'),
+            name: z.string().describe('Human-readable name.'),
+            description: z.string().describe('Route description.'),
+            route: z
+                .string()
+                .describe('Full route path usable in eia_describe_route or eia_query_route.'),
+            isLeaf: z
+                .boolean()
+                .describe('True when this child is a queryable leaf route with data.'),
+        })
+            .describe('A child route entry.'))
+            .describe('Child entries under the browsed path.'),
+        isLeaf: z
+            .boolean()
+            .describe('True when the browsed path itself is a leaf route — no children to drill into; use eia_describe_route instead.'),
+    }),
+    errors: [
+        {
+            reason: 'route_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Path does not exist in the EIA taxonomy.',
+            recovery: 'Call eia_browse_routes without a path to see valid top-level categories.',
+        },
+    ],
+    handler(input, ctx) {
+        ctx.log.info('Executing eia_browse_routes', { path: input.path });
+        return getEiaApiService().browse(input.path, ctx);
+    },
+    format: (result) => {
+        const lines = [];
+        if (result.isLeaf && result.children.length === 0) {
+            lines.push(`**${result.path}** is a leaf route — use eia_describe_route to inspect its facets and columns.`);
+        }
+        const label = result.path ? `**${result.path}**` : 'root';
+        if (result.children.length > 0) {
+            lines.push(`Children of ${label} (${result.children.length}):\n`);
+        }
+        for (const c of result.children) {
+            const tag = c.isLeaf ? '[leaf]' : '[cat]';
+            lines.push(`${tag} **${c.route}** (${c.id}) — ${c.name}`);
+            if (c.description)
+                lines.push(`  ${c.description}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=browse-routes.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_describe. Lists canvas
+ * dataframes materialized by eia_query_route with provenance, TTL, row count,
+ * and column schema. Lazy-sweeps expired tables before responding so the list
+ * is always current.
+ * @module mcp-server/tools/definitions/dataframe-describe.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeDescribeTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    dataframes: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source_tool: z.ZodString;
+        query_params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        row_count: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        max_rows: z.ZodOptional<z.ZodNumber>;
+        column_schema: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            nullable: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "DataCanvas service is not configured for this deployment.";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-describe.tool.d.ts.map

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-describe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-describe.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;GAqHhC,CAAC"}

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

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_describe. Lists canvas
+ * dataframes materialized by eia_query_route with provenance, TTL, row count,
+ * and column schema. Lazy-sweeps expired tables before responding so the list
+ * is always current.
+ * @module mcp-server/tools/definitions/dataframe-describe.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';
+export const dataframeDescribeTool = tool('eia_dataframe_describe', {
+    title: 'Describe EIA Dataframes',
+    description: 'List canvas dataframes (df_<id>) materialized by eia_query_route, with provenance, TTL, row count, and column schema. Lazy-sweeps expired tables before responding so the list is always current. Pass a specific name to inspect one dataframe; omit to list all active dataframes for this tenant.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'DataCanvas service is not configured for this deployment.',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        name: z
+            .string()
+            .optional()
+            .describe('df_<id> handle to describe a single dataframe. Omit to list all active dataframes.'),
+    }),
+    output: z.object({
+        dataframes: z
+            .array(z
+            .object({
+            name: z.string().describe('Canvas table name (df_<id>).'),
+            source_tool: z.string().describe('Tool that produced this dataframe.'),
+            query_params: z
+                .record(z.string(), z.unknown())
+                .describe('Input parameters the source tool was called with.'),
+            created_at: z.string().describe('ISO 8601 creation timestamp.'),
+            expires_at: z.string().describe('ISO 8601 expiry timestamp (sliding TTL).'),
+            row_count: z.number().describe('Rows materialized in the dataframe.'),
+            truncated: z
+                .boolean()
+                .describe('True when the EIA upstream had more rows than were registered.'),
+            max_rows: z
+                .number()
+                .optional()
+                .describe('Materialization cap that produced truncated, when applicable.'),
+            column_schema: z
+                .array(z
+                .object({
+                name: z.string().describe('Column name.'),
+                type: z.string().describe('DuckDB column type (VARCHAR for EIA data values).'),
+                nullable: z.boolean().describe('Whether the column permits NULL.'),
+            })
+                .describe('A column in the dataframe schema.'))
+                .describe('Column schema (all EIA data columns are VARCHAR and nullable).'),
+        })
+            .describe('A canvas dataframe entry.'))
+            .describe('Active dataframes for this tenant, newest first. Empty when none are registered.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const entries = await bridge.describe(ctx, input.name);
+        return {
+            dataframes: entries.map((meta) => ({
+                name: meta.tableName,
+                source_tool: meta.sourceTool,
+                query_params: meta.queryParams,
+                created_at: meta.createdAt,
+                expires_at: meta.expiresAt,
+                row_count: meta.rowCount,
+                truncated: meta.truncated,
+                max_rows: meta.maxRows,
+                column_schema: meta.columnSchema.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    nullable: c.nullable ?? true,
+                })),
+            })),
+        };
+    },
+    format: (result) => {
+        if (result.dataframes.length === 0) {
+            return [{ type: 'text', text: 'No active dataframes.' }];
+        }
+        const lines = [`**${result.dataframes.length} active dataframe(s):**\n`];
+        for (const df of result.dataframes) {
+            const truncated = df.truncated
+                ? ` (truncated${df.max_rows != null ? ` at ${df.max_rows}` : ''})`
+                : '';
+            lines.push(`### ${df.name}`);
+            lines.push(`- Source: ${df.source_tool}`);
+            lines.push(`- Rows: ${df.row_count}${truncated}`);
+            lines.push(`- Created: ${df.created_at} — Expires: ${df.expires_at}`);
+            const paramEntries = Object.entries(df.query_params);
+            if (paramEntries.length > 0) {
+                const params = paramEntries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
+                lines.push(`- Params: ${params}`);
+            }
+            const cols = df.column_schema
+                .map((c) => `${c.name}:${c.type}(nullable=${c.nullable})`)
+                .join(', ');
+            lines.push(`- Columns: ${cols}`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n').trimEnd() }];
+    },
+});
+//# sourceMappingURL=dataframe-describe.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_drop. Drops a canvas
+ * dataframe by name. Opt-in — only registered in createApp() when
+ * EIA_DATAFRAME_DROP_ENABLED=true. Idempotent: returns dropped=false when
+ * nothing matched. TTL (default 24 h) handles cleanup in normal operation;
+ * this tool is for manual cleanup in long-running sessions.
+ * @module mcp-server/tools/definitions/dataframe-drop.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeDropTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    dropped: z.ZodBoolean;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "DataCanvas service is not configured for this deployment.";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-drop.tool.d.ts.map

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_drop. Drops a canvas
+ * dataframe by name. Opt-in — only registered in createApp() when
+ * EIA_DATAFRAME_DROP_ENABLED=true. Idempotent: returns dropped=false when
+ * nothing matched. TTL (default 24 h) handles cleanup in normal operation;
+ * this tool is for manual cleanup in long-running sessions.
+ * @module mcp-server/tools/definitions/dataframe-drop.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';
+export const dataframeDropTool = tool('eia_dataframe_drop', {
+    title: 'Drop EIA Dataframe',
+    description: 'Drop a canvas dataframe by name. Idempotent — returns dropped=false when nothing matched. Use to free canvas resources ahead of the per-table TTL when an analysis is complete. In normal operation, TTL cleanup (default 24 h, sliding) is sufficient and this tool is unnecessary. Only available when EIA_DATAFRAME_DROP_ENABLED=true.',
+    annotations: {
+        readOnlyHint: false,
+        idempotentHint: true,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'DataCanvas service is not configured for this deployment.',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        name: z.string().min(1).describe('df_<id> handle to drop.'),
+    }),
+    output: z.object({
+        name: z.string().describe('The name that was requested.'),
+        dropped: z
+            .boolean()
+            .describe('True when the dataframe existed and was removed; false when nothing matched.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const dropped = await bridge.drop(ctx, input.name);
+        ctx.log.info('EIA dataframe drop requested', { name: input.name, dropped });
+        return { name: input.name, dropped };
+    },
+    format: (result) => [
+        {
+            type: 'text',
+            text: result.dropped ? `Dropped ${result.name}.` : `${result.name} not found.`,
+        },
+    ],
+});
+//# sourceMappingURL=dataframe-drop.tool.js.map

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-drop.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-drop.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAE5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,oBAAoB,EAAE;IAC1D,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,2UAA2U;IAC7U,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;QACrB,aAAa,EAAE,KAAK;KACrB;IAED,MAAM,EAAE;QACN;YACE,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,2DAA2D;YACjE,QAAQ,EAAE,iFAAiF;SAC5F;KACF;IAED,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;KAC5D,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QACzD,OAAO,EAAE,CAAC;aACP,OAAO,EAAE;aACT,QAAQ,CAAC,8EAA8E,CAAC;KAC5F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,8CAA8C,EAAE;gBACnF,GAAG,GAAG,CAAC,WAAW,CAAC,oBAAoB,CAAC;aACzC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5E,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,aAAa;SAC/E;KACF;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_query. Runs a single-statement
+ * SELECT against canvas dataframes registered by eia_query_route. Four-layer
+ * read-only enforcement: text deny-list, statement count, statement type, and
+ * EXPLAIN-plan walk in the framework; plus bridge-layer system-catalog deny.
+ * EIA data values are VARCHAR — cast to DOUBLE for arithmetic.
+ * @module mcp-server/tools/definitions/dataframe-query.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeQueryTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    sql: z.ZodString;
+    register_as: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodNumber>;
+    row_limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    row_count: z.ZodNumber;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    registered_as: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "DataCanvas service is not configured for this deployment.";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-query.tool.d.ts.map

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

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

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

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Tool definition for eia_dataframe_query. Runs a single-statement
+ * SELECT against canvas dataframes registered by eia_query_route. Four-layer
+ * read-only enforcement: text deny-list, statement count, statement type, and
+ * EXPLAIN-plan walk in the framework; plus bridge-layer system-catalog deny.
+ * EIA data values are VARCHAR — cast to DOUBLE for arithmetic.
+ * @module mcp-server/tools/definitions/dataframe-query.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';
+export const dataframeQueryTool = tool('eia_dataframe_query', {
+    title: 'Query EIA Dataframes',
+    description: 'Run a single-statement SELECT against canvas dataframes registered by eia_query_route. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the df_<id> handles returned by eia_query_route or listed by eia_dataframe_describe. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer. EIA data values are VARCHAR — use CAST(col AS DOUBLE) for arithmetic and aggregation. Optional register_as chains results as a new dataframe with a fresh TTL.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'DataCanvas service is not configured for this deployment.',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        sql: z
+            .string()
+            .min(1)
+            .describe('Single-statement SELECT against df_<id> tables. EIA data columns are VARCHAR — use CAST(col AS DOUBLE) for arithmetic. Example: SELECT period, CAST(value AS DOUBLE) AS val FROM df_XXXXX ORDER BY period'),
+        register_as: z
+            .string()
+            .optional()
+            .describe('When set, persist the result as a new dataframe with a fresh TTL. Use to chain analyses without re-running upstream queries. Conflicts with an existing name throw Conflict.'),
+        preview: z
+            .number()
+            .int()
+            .min(0)
+            .max(10000)
+            .optional()
+            .describe('Rows to include in the immediate response. Defaults to row_limit. Set lower when chaining via register_as and only a sample is needed inline.'),
+        row_limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(10000)
+            .default(1000)
+            .describe('Hard cap on rows materialized in the response (default 1000, max 10000).'),
+    }),
+    output: z.object({
+        columns: z.array(z.string()).describe('Column names in projection order.'),
+        row_count: z
+            .number()
+            .describe('Total rows the query produced (may exceed rows.length when capped).'),
+        rows: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Materialized rows, bounded by preview / row_limit.'),
+        registered_as: z
+            .string()
+            .optional()
+            .describe('Set when register_as was supplied and the new dataframe was materialized.'),
+        expires_at: z
+            .string()
+            .optional()
+            .describe('ISO 8601 expiry for the newly registered dataframe, when applicable.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const { result, meta } = await bridge.query(ctx, input.sql, {
+            ...(input.register_as !== undefined && { registerAs: input.register_as }),
+            ...(input.preview !== undefined && { preview: input.preview }),
+            rowLimit: input.row_limit,
+            sourceTool: 'eia_dataframe_query',
+            queryParams: { sql: input.sql },
+        });
+        ctx.log.info('EIA dataframe query executed', {
+            rowCount: result.rowCount,
+            returned: result.rows.length,
+            registeredAs: meta?.tableName,
+        });
+        return {
+            columns: result.columns,
+            row_count: result.rowCount,
+            rows: result.rows,
+            registered_as: meta?.tableName,
+            expires_at: meta?.expiresAt,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        if (result.registered_as) {
+            lines.push(`Registered as ${result.registered_as} (expires ${result.expires_at ?? 'unknown'}).`);
+        }
+        const cappedNote = result.row_count > result.rows.length
+            ? ` (showing ${result.rows.length} of ${result.row_count})`
+            : '';
+        lines.push(`**${result.row_count} rows**${cappedNote}\n`);
+        if (result.rows.length === 0) {
+            lines.push('_No rows._');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        const header = `| ${result.columns.join(' | ')} |`;
+        const sep = `| ${result.columns.map(() => '---').join(' | ')} |`;
+        lines.push(header, sep);
+        for (const row of result.rows) {
+            const cells = result.columns.map((c) => {
+                const v = row[c];
+                if (v === null || v === undefined)
+                    return '';
+                if (typeof v === 'string')
+                    return v.replace(/\|/g, '\\|');
+                if (typeof v === 'object')
+                    return JSON.stringify(v).replace(/\|/g, '\\|');
+                return String(v);
+            });
+            lines.push(`| ${cells.join(' | ')} |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=dataframe-query.tool.js.map

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

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

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

@@ -0,0 +1,58 @@
+/**
+ * @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 { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const describeRouteTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    route: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    route: z.ZodString;
+    description: z.ZodString;
+    facets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        values: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            alias: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    data_columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        alias: z.ZodString;
+        units: z.ZodString;
+    }, z.core.$strip>>;
+    frequencies: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        query: z.ZodString;
+        format: z.ZodString;
+    }, z.core.$strip>>;
+    date_range: z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strip>;
+    default_frequency: z.ZodString;
+    default_date_format: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "route_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Route does not exist in the EIA taxonomy.";
+    readonly recovery: "Use eia_browse_routes or eia_search_routes to discover valid leaf route paths.";
+}, {
+    readonly reason: "route_not_queryable";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Route is a category node with sub-routes, not a queryable leaf.";
+    readonly recovery: "Use eia_browse_routes to drill into sub-routes, or eia_search_routes to find leaf routes.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly retryable: true;
+    readonly when: "EIA rate limit hit during facet fan-out.";
+    readonly recovery: "Back off and retry; use a production EIA API key for higher rate limits.";
+}]>;
+//# sourceMappingURL=describe-route.tool.d.ts.map

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

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