@cyanheads/eia-energy-mcp-server 0.2.0

package/dist/services/eia/route-cache.js

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview In-process route tree cache and Fuse.js fuzzy search index.
+ * The route tree is fetched lazily on first use and held for the process
+ * lifetime — EIA's taxonomy is stable between API releases and restarting the
+ * server is the appropriate refresh mechanism. The Fuse.js index is built once
+ * after the tree is populated and includes STEO series names so natural-language
+ * queries resolve to specific seriesId values.
+ * @module services/eia/route-cache
+ */
+import Fuse, {} from 'fuse.js';
+let _cache;
+/**
+ * Normalize a description string from the EIA API. EIA descriptions often
+ * contain embedded `\r\n` + leading whitespace (source-level line wrapping).
+ * Collapse to a clean single-line string.
+ */
+export function normalizeDescription(desc) {
+    if (!desc)
+        return '';
+    return desc
+        .replace(/\r/g, '')
+        .replace(/\s*\n\s*/g, ' ')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/** Walk the raw route tree and collect all nodes into a flat path→node map. */
+export function buildNodeMap(nodes, parentPath, map) {
+    for (const node of nodes) {
+        const path = parentPath ? `${parentPath}/${node.id}` : node.id;
+        // Normalize description in place so all tools that read from cache get clean strings
+        const normalized = node.description !== undefined
+            ? { ...node, description: normalizeDescription(node.description) }
+            : node;
+        map.set(path, normalized);
+        if (normalized.routes?.length) {
+            buildNodeMap(normalized.routes, path, map);
+        }
+    }
+}
+/**
+ * Classify a raw node as a leaf. A node is a leaf when it has `frequency`,
+ * `facets`, or `data` fields (queryable data endpoint) rather than a `routes`
+ * array. Root-level nodes with no sub-routes and no data fields are treated as
+ * leaves (e.g. steo).
+ */
+export function isLeafNode(node) {
+    if (node.frequency !== undefined)
+        return true;
+    if (node.facets !== undefined)
+        return true;
+    if (node.data !== undefined)
+        return true;
+    // A node with no routes array and no data/frequency is still a leaf candidate
+    return !node.routes?.length;
+}
+/** Build search index entries from a flat node map. */
+function buildEntries(nodeMap) {
+    const entries = [];
+    for (const [route, node] of nodeMap) {
+        const parts = route.split('/');
+        const category = parts.length > 1 ? parts[0] : undefined;
+        entries.push({
+            route,
+            name: node.name,
+            description: node.description ?? '',
+            isLeaf: isLeafNode(node),
+            category,
+        });
+    }
+    return entries;
+}
+const FUSE_OPTIONS = {
+    keys: [
+        { name: 'name', weight: 2 },
+        { name: 'description', weight: 1.5 },
+        { name: 'route', weight: 1 },
+        { name: 'category', weight: 0.5 },
+    ],
+    threshold: 0.4,
+    includeScore: true,
+    minMatchCharLength: 2,
+};
+/** Initialize the cache with the fetched route tree and optional STEO entries. */
+export function initRouteCache(topLevelNodes, steoSeriesEntries) {
+    const nodeMap = new Map();
+    buildNodeMap(topLevelNodes, '', nodeMap);
+    const routeEntries = buildEntries(nodeMap);
+    const allEntries = [...routeEntries, ...steoSeriesEntries];
+    _cache = {
+        nodeMap,
+        fuseIndex: new Fuse(allEntries, FUSE_OPTIONS),
+        entries: allEntries,
+    };
+}
+/** Return the cache, throwing if not yet initialized. */
+export function getRouteCache() {
+    if (!_cache)
+        throw new Error('Route cache not initialized');
+    return _cache;
+}
+/** True when the cache has been populated. */
+export function isRouteCacheReady() {
+    return _cache !== undefined;
+}
+/** Reset the cache (used in tests). */
+export function _resetRouteCache() {
+    _cache = undefined;
+}
+/** Get a node by route path. Returns undefined when not found. */
+export function getNode(path) {
+    if (!_cache)
+        return;
+    if (!path) {
+        // Root — return a synthetic node with top-level children
+        return;
+    }
+    return _cache.nodeMap.get(path);
+}
+/**
+ * Get children of a given path. For root (empty path), returns top-level nodes.
+ * Returns empty array when path has no children.
+ */
+export function getChildren(path) {
+    if (!_cache)
+        return [];
+    const children = [];
+    if (!path) {
+        // Root: find all nodes whose route has no '/' separator
+        for (const [route, node] of _cache.nodeMap) {
+            if (!route.includes('/')) {
+                children.push({ id: node.id, route, node });
+            }
+        }
+    }
+    else {
+        // Find all nodes whose route is exactly `${path}/${id}`
+        const prefix = `${path}/`;
+        for (const [route, node] of _cache.nodeMap) {
+            if (route.startsWith(prefix) && !route.slice(prefix.length).includes('/')) {
+                const id = route.slice(prefix.length);
+                children.push({ id, route, node });
+            }
+        }
+    }
+    return children;
+}
+/** Fuzzy search across the index. Returns ranked matches. */
+export function searchRoutes(query, limit) {
+    if (!_cache)
+        return [];
+    const results = _cache.fuseIndex.search(query, { limit });
+    return results.map((r) => ({
+        entry: r.item,
+        score: r.score ?? 1,
+    }));
+}
+/** Total number of indexed entries. */
+export function getIndexSize() {
+    return _cache?.entries.length ?? 0;
+}
+/** Add STEO series entries to an already-initialized cache. */
+export function addSteoSeriesToIndex(steoEntries) {
+    if (!_cache)
+        return;
+    _cache.entries.push(...steoEntries);
+    _cache.fuseIndex = new Fuse(_cache.entries, FUSE_OPTIONS);
+}
+//# sourceMappingURL=route-cache.js.map

package/dist/services/eia/route-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-cache.js","sourceRoot":"","sources":["../../../src/services/eia/route-cache.ts"],"names":[],"mappings":"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"}

package/dist/services/eia/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview EIA API v2 domain types — raw API shapes and normalized domain
+ * objects used across the service layer and tool definitions.
+ * @module services/eia/types
+ */
+/** A single entry in the EIA route tree (not yet classified as leaf/category). */
+export interface RouteEntry {
+    description: string;
+    id: string;
+    /** True when this route is a leaf (queryable data endpoint). */
+    isLeaf: boolean;
+    name: string;
+    route: string;
+}
+/** Full route tree node as returned by the EIA v2 API browse endpoint. */
+export interface RawRouteNode {
+    /**
+     * Present on leaf nodes. Two shapes exist in the wild:
+     *   Standard: `{ colId: { alias: string, units: string }, ... }`
+     *   Value-array: `{ value: [] }` — time-series routes with a single unnamed column
+     */
+    data?: Record<string, {
+        alias: string;
+        units: string;
+    } | unknown[]>;
+    defaultDateFormat?: string;
+    defaultFrequency?: string;
+    description?: string;
+    endPeriod?: string;
+    /** Present on leaf nodes */
+    facets?: RawFacetMeta[];
+    /** Present on leaf nodes */
+    frequency?: RawFrequency[];
+    id: string;
+    name: string;
+    routes?: RawRouteNode[];
+    startPeriod?: string;
+}
+export interface RawFrequency {
+    description: string;
+    format: string;
+    id: string;
+    query: string;
+}
+/** Facet metadata from the route metadata endpoint (no values). */
+export interface RawFacetMeta {
+    description: string;
+    id: string;
+}
+/** Individual facet value from /v2/{route}/facet/{facetId}. */
+export interface RawFacetValue {
+    alias?: string;
+    id: string;
+    name: string;
+}
+/** Response from /v2/{route}/facet/{facetId}. */
+export interface RawFacetResponse {
+    facets: RawFacetValue[];
+    totalFacets: number;
+}
+/** Normalized facet with all values populated. */
+export interface Facet {
+    description: string;
+    id: string;
+    values: Array<{
+        id: string;
+        name: string;
+        alias?: string;
+    }>;
+}
+/** Normalized data column. */
+export interface DataColumn {
+    alias: string;
+    id: string;
+    units: string;
+}
+/** Full normalized route metadata (leaf only). */
+export interface RouteMetadata {
+    dataColumns: DataColumn[];
+    dateRange: {
+        start: string;
+        end: string;
+    };
+    defaultDateFormat: string;
+    defaultFrequency: string;
+    description: string;
+    facets: Facet[];
+    frequencies: RawFrequency[];
+    route: string;
+}
+/** A data row from /v2/{route}/data/. All values are strings per EIA API. */
+export type DataRow = Record<string, string | null>;
+/** Response from /v2/{route}/data/. */
+export interface DataResponse {
+    data: DataRow[];
+    dateFormat: string;
+    frequency: string;
+    total: number;
+    warnings: string[] | undefined;
+}
+/** Entry in the Fuse.js search index. */
+export interface SearchIndexEntry {
+    category: string | undefined;
+    description: string;
+    /**
+     * Pre-built filter hint for routes that require a specific facet value to
+     * query. Present on STEO series entries so callers can pass the seriesId
+     * directly to eia_query_route without parsing the description string.
+     */
+    filter_hint?: Record<string, string>;
+    isLeaf: boolean;
+    name: string;
+    route: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/eia/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/eia/types.ts"],"names":[],"mappings":"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"}

package/dist/services/eia/types.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview EIA API v2 domain types — raw API shapes and normalized domain
+ * objects used across the service layer and tool definitions.
+ * @module services/eia/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/eia/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/eia/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@cyanheads/eia-energy-mcp-server",
+  "version": "0.2.0",
+  "mcpName": "io.github.cyanheads/eia-energy-mcp-server",
+  "description": "Browse and query the U.S. Energy Information Administration API v2 — electricity, petroleum, natural gas, coal, forecasts, and more via MCP. STDIO or Streamable HTTP.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "eia-energy-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "changelog/",
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md",
+    "Dockerfile",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
+    "clean": "bun run scripts/clean.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
+    "tree": "bun run scripts/tree.ts",
+    "format": "biome check --write --unsafe .",
+    "lint:mcp": "bun run scripts/lint-mcp.ts",
+    "lint:packaging": "bun run scripts/lint-packaging.ts",
+    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/eia-energy-mcp-server.mcpb",
+    "changelog:build": "bun run scripts/build-changelog.ts",
+    "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "list-skills": "bun run scripts/list-skills.ts",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js",
+    "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
+  },
+  "keywords": [
+    "eia",
+    "energy",
+    "energy-information-administration",
+    "electricity",
+    "petroleum",
+    "natural-gas",
+    "coal",
+    "energy-data",
+    "energy-api",
+    "steo",
+    "us-energy",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "typescript",
+    "bun",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/eia-energy-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cyanheads/eia-energy-mcp-server/issues"
+  },
+  "homepage": "https://github.com/cyanheads/eia-energy-mcp-server#readme",
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/eia-energy-mcp-server#readme)",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
+  "license": "Apache-2.0",
+  "packageManager": "bun@1.3.0",
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.9.6",
+    "@duckdb/node-api": "^1.5.3-r.1",
+    "fuse.js": "^7.3.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@types/node": "^25.9.1",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  }
+}

package/server.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cyanheads/eia-energy-mcp-server",
+  "description": "Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.",
+  "repository": {
+    "url": "https://github.com/cyanheads/eia-energy-mcp-server",
+    "source": "github"
+  },
+  "version": "0.2.0",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://eia-energy.caseyjhand.com/mcp"
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/eia-energy-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.2.0",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:stdio"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "EIA_API_KEY",
+          "description": "Free API key from api.eia.gov. Required — all requests use this as the api_key query parameter.",
+          "format": "string",
+          "isRequired": true
+        },
+        {
+          "name": "EIA_DATASET_TTL_SECONDS",
+          "description": "Per-table TTL for DataCanvas dataframes in seconds.",
+          "format": "string",
+          "isRequired": false,
+          "default": "86400"
+        },
+        {
+          "name": "EIA_DATAFRAME_DROP_ENABLED",
+          "description": "Set to 'true' to expose eia_dataframe_drop for manual canvas cleanup.",
+          "format": "string",
+          "isRequired": false,
+          "default": "false"
+        },
+        {
+          "name": "CANVAS_PROVIDER_TYPE",
+          "description": "Set to 'duckdb' to enable DataCanvas spillover for large query result sets (Node.js only).",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/eia-energy-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.2.0",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:http"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "EIA_API_KEY",
+          "description": "Free API key from api.eia.gov. Required — all requests use this as the api_key query parameter.",
+          "format": "string",
+          "isRequired": true
+        },
+        {
+          "name": "EIA_DATASET_TTL_SECONDS",
+          "description": "Per-table TTL for DataCanvas dataframes in seconds.",
+          "format": "string",
+          "isRequired": false,
+          "default": "86400"
+        },
+        {
+          "name": "EIA_DATAFRAME_DROP_ENABLED",
+          "description": "Set to 'true' to expose eia_dataframe_drop for manual canvas cleanup.",
+          "format": "string",
+          "isRequired": false,
+          "default": "false"
+        },
+        {
+          "name": "CANVAS_PROVIDER_TYPE",
+          "description": "Set to 'duckdb' to enable DataCanvas spillover for large query result sets (Node.js only).",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "MCP_HTTP_HOST",
+          "description": "The hostname for the HTTP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "127.0.0.1"
+        },
+        {
+          "name": "MCP_HTTP_PORT",
+          "description": "The port to run the HTTP server on.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3010"
+        },
+        {
+          "name": "MCP_HTTP_ENDPOINT_PATH",
+          "description": "The endpoint path for the MCP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "/mcp"
+        },
+        {
+          "name": "MCP_PUBLIC_URL",
+          "description": "Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "MCP_AUTH_MODE",
+          "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
+          "format": "string",
+          "isRequired": false,
+          "default": "none"
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3010/mcp"
+      }
+    }
+  ]
+}