Tools

Four route tools cover the two-phase EIA workflow — find the right dataset route, then pull the data. Three DataCanvas tools add SQL over staged results and are listed only where a canvas is configured (CANVAS_PROVIDER_TYPE=duckdb); eia_dataframe_drop needs its own opt-in on top. A default deployment therefore advertises four tools, all of them working:

eia_browse_routes

Walk the EIA dataset taxonomy from root to leaf.

• Root call returns 14 top-level categories: electricity, petroleum, natural-gas, coal, international, total-energy, steo, aeo, ieo, seds, crude-oil-imports, nuclear-outages, densified-biomass, co2-emissions
• Intermediate paths return subcategories; leaf routes are flagged so callers know when to switch to eia_describe_route
• STEO (Short-Term Energy Outlook) is a flat leaf with 1,469 named series — no sub-routes

eia_describe_route

Full schema for a leaf route. Required before constructing facet filters.

• Returns facets with valid values (fetched via per-facet API calls and cached in-process)
• Returns data column names, units, frequency options, and date range
• Each facet returns at most EIA_FACET_VALUE_CAP values, alongside value_count and values_truncated. Pass facet with values_offset to page one facet past the cap — the cap shapes this tool's response only, and the in-process cache keeps every value
• That window is the same on both client surfaces: content[] renders every value structuredContent carries, so both name the same next call
• values_offset applies to every facet in the response. One past a facet's last value empties that facet's window and returns a notice naming the facet and its value_count, so an overshoot never reads like a fully enumerated facet
• In content[] a value reads as id=name (alias), with the alias left off when it only restates the pair — EIA supplies (IN) Indiana beside IN=Indiana on most values. An alias that adds something, such as Region: (MAT) Middle Atlantic, still prints, and the alias field itself is unchanged
• A value EIA sends without a name is labelled from its alias, then from its id — the id is what filters, so the value is kept. A value EIA sends without an id is dropped, having nothing to filter with
• eia_search_routes and eia_browse_routes resolve the route path; this tool provides the filter vocabulary

eia_search_routes

Fuzzy search across the in-memory route index.

• Indexes route names, descriptions, and category labels — plus STEO's 1,469 series names and facet values
• Resolves natural language ("natural gas spot prices", "ethanol net imports") to queryable route paths, and a fuel-type or sector term ("wind", "anthracite coal") to the route that exposes it, with a filter_hint to pass straight to eia_query_route
• A multi-term query is also matched term by term, so combining a commodity, a metric, and a sector ("electricity price residential", "coal generation industrial sector") reaches the route carrying that data even when no single entry reads like the whole phrase. Each result keeps the better of its whole-phrase and per-term score; a single-term query takes the phrase path alone
• score runs 0 (exact) to 1 (no match), lower is better; above 0.72 the match is unreliable and the query is worth narrowing. bun run eval:search scores a labelled query battery against a live corpus, which is where that number comes from
• The first call waits for the whole corpus to warm — 24–30 s measured against the live API from cold, and never more than 45 s, so a degraded upstream cannot hold the call past a client's request timeout. Every later search is served from the in-process Fuse.js index in tens of milliseconds, with no upstream cost
• indexComplete reports whether the answer was ranked against the whole corpus; when it is false, indexGaps names the routes and index passes that are missing, so a short result set is never mistaken for a settled one

eia_query_route

Pull data from a leaf route.

• Facet filters keyed by facet ID (e.g. { "stateid": "TX", "sectorid": ["RES", "COM"] })
• Date range and frequency selection; valid values discoverable via eia_describe_route
• Pagination via offset/length (max 5,000 rows per page); total row count in response
• All numeric values arrive as strings from the EIA API — units appear as inline {col}-units fields per row
• Route paths accept leading, trailing, and doubled slashes — an EIA-doc spelling like /electricity/retail-sales/ resolves to the same route, and the response echoes the canonical form back
• DataCanvas staging is opt-in per call via stage: true: further pages are fetched and the accumulated rows are staged as a dataset (df_<id>) for SQL, bounded by EIA_CANVAS_MAX_ROWS. The response note names how many rows actually reached the table. Left off (the default), a query costs one upstream request however large the match is, and the note names stage: true as the way to reach the rest.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

EIA-specific: