@cyanheads/eia-energy-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,274 @@
+<div align="center">
+  <h1>@cyanheads/eia-energy-mcp-server</h1>
+  <p><b>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.</b>
+  <div>7 Tools</div>
+  </p>
+</div>
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/eia-energy-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/eia-energy-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/eia-energy-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+
+[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/eia-energy-mcp-server/releases/latest/download/eia-energy-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=eia-energy-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZWlhLWVuZXJneS1tY3Atc2VydmVyIl0sImVudiI6eyJFSUFfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22eia-energy-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/eia-energy-mcp-server%22%5D%2C%22env%22%3A%7B%22EIA_API_KEY%22%3A%22your-api-key%22%7D%7D)
+
+[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+
+</div>
+
+<div align="center">
+
+**Public Hosted Server:** [https://eia-energy.caseyjhand.com/mcp](https://eia-energy.caseyjhand.com/mcp)
+
+</div>
+
+---
+
+## Tools
+
+Seven tools covering the two-phase EIA workflow — find the right dataset route, pull the data, and query spilled results via SQL:
+
+| Tool | Description |
+|:-----|:------------|
+| `eia_browse_routes` | Lists child routes under a given path in the EIA dataset taxonomy. Start at root to see top-level categories, then drill into subcategories and leaf routes. |
+| `eia_describe_route` | Returns full metadata for a leaf route: available facets with valid values, data column names, frequency options, units, and date range. Call before `eia_query_route` to understand filter options. |
+| `eia_search_routes` | Fuzzy text search across route names, descriptions, and category labels. Resolves natural-language queries like "gasoline retail prices" or "solar capacity by state" to matching route paths. |
+| `eia_query_route` | Fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. Spills large result sets to a DataCanvas table for SQL analysis. |
+| `eia_dataframe_describe` | Lists active DataCanvas dataframes created by prior `eia_query_route` calls. Shows table name, column names and types, row count, and canvas ID. |
+| `eia_dataframe_query` | Runs a read-only SQL SELECT against a DataCanvas dataframe by canvas ID or table name. |
+| `eia_dataframe_drop` | Drops a DataCanvas dataframe, freeing its memory. Only exposed when `EIA_DATAFRAME_DROP_ENABLED=true`. |
+
+### `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
+- `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
+- Resolves natural language ("natural gas spot prices", "ethanol net imports") to queryable route paths
+- Route tree is cached in-process at first call; subsequent searches hit the Fuse.js index with no upstream cost
+
+---
+
+### `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
+- DataCanvas spillover when result set exceeds `length`: returns `canvas_id` for SQL queries over the full dataset
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@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:
+
+- Full coverage of EIA API v2 — all 14 top-level dataset categories
+- In-process route tree cache with Fuse.js fuzzy index — built once at startup, no repeated upstream calls
+- Per-route facet cache via `Promise.all` fan-out — valid filter values available without re-fetching
+- STEO series names (1,469 entries) indexed for natural-language discovery
+- DataCanvas (DuckDB) opt-in for tabular spillover — graceful degradation when unavailable
+
+## Getting started
+
+Get a free API key at [api.eia.gov](https://www.eia.gov/opendata/), then add the following to your MCP client configuration file.
+
+```json
+{
+  "mcpServers": {
+    "eia": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/eia-energy-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
+        "EIA_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Or with npx (no Bun required):
+
+```json
+{
+  "mcpServers": {
+    "eia": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/eia-energy-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
+        "EIA_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "eia": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "-e", "EIA_API_KEY=your-api-key",
+        "ghcr.io/cyanheads/eia-energy-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+For Streamable HTTP, set the transport and start the server:
+
+```sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 EIA_API_KEY=your-key bun run start:http
+# Server listens at http://localhost:3010/mcp
+```
+
+### Prerequisites
+
+- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- A free EIA API key from [api.eia.gov](https://www.eia.gov/opendata/). The `DEMO_KEY` hits rate limits quickly; a real key is required for sustained use.
+
+### Installation
+
+1. **Clone the repository:**
+
+```sh
+git clone https://github.com/cyanheads/eia-energy-mcp-server.git
+```
+
+2. **Navigate into the directory:**
+
+```sh
+cd eia-energy-mcp-server
+```
+
+3. **Install dependencies:**
+
+```sh
+bun install
+```
+
+4. **Configure environment:**
+
+```sh
+cp .env.example .env
+# edit .env and set required vars (at minimum, EIA_API_KEY)
+```
+
+## Configuration
+
+All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `EIA_API_KEY` | **Required.** Free API key from api.eia.gov — appended as `api_key` on every request. | — |
+| `EIA_BASE_URL` | EIA API base URL. | `https://api.eia.gov/v2` |
+| `EIA_DATASET_TTL_SECONDS` | Per-table TTL for DataCanvas dataframes in seconds. | `86400` (24 h) |
+| `EIA_DATAFRAME_DROP_ENABLED` | Set to `true` to expose `eia_dataframe_drop`. Off by default to avoid accidental canvas cleanup. | `false` |
+| `CANVAS_PROVIDER_TYPE` | Set to `duckdb` to enable DataCanvas spillover for large result sets (Node only). | — |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
+| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |
+| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | — |
+| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
+| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
+| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
+| `OTEL_ENABLED` | Enable OpenTelemetry instrumentation. | `false` |
+
+## Running the server
+
+### Local development
+
+- **Build and run:**
+
+  ```sh
+  # One-time build
+  bun run rebuild
+
+  # Run the built server
+  bun run start:stdio
+  # or
+  bun run start:http
+  ```
+
+- **Run checks and tests:**
+
+  ```sh
+  bun run devcheck   # Lint, format, typecheck, security
+  bun run test       # Vitest test suite
+  bun run lint:mcp   # Validate MCP definitions against spec
+  ```
+
+## Project structure
+
+| Directory | Purpose |
+|:----------|:--------|
+| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |
+| `src/config` | Server-specific environment variable parsing and validation with Zod. |
+| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — browse, describe, search, query, and three DataCanvas dataframe tools. |
+| `src/services/eia` | EIA API v2 service — route tree cache, Fuse.js index, facet fan-out, HTTP client. |
+| `src/services/canvas-bridge` | DataCanvas bridge — registers EIA query results as DuckDB dataframes, routes SQL queries. |
+| `tests/` | Unit and integration tests mirroring `src/`. |
+| `docs/` | Design documents (`design.md`, `idea.md`). |
+
+## Development guide
+
+See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+
+- Handlers throw, framework catches — no `try/catch` in tool logic
+- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
+- Always call `eia_describe_route` before `eia_query_route` — facet values require a separate API fan-out and are not embedded in route metadata
+- Wrap EIA responses: validate raw → normalize to domain type → return output schema; data values are strings — never coerce silently
+
+## Contributing
+
+Issues and pull requests are welcome. Run checks and tests before submitting:
+
+```sh
+bun run devcheck
+bun run test
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,18 @@
+---
+summary: "Initial scaffold from @cyanheads/mcp-ts-core with tool-surface design for the EIA API v2."
+breaking: false
+security: false
+---
+
+# 0.1.0 — 2026-05-21
+
+## Added
+
+- Project scaffolded from `@cyanheads/mcp-ts-core`.
+- Idea seed (`docs/idea.md`) covering the EIA data domain: electricity, petroleum, natural gas, coal, international, STEO forecasts, and emissions.
+- Tool-surface design (`docs/design.md`) for four tools: `eia_browse_routes`, `eia_describe_route`, `eia_search_routes`, `eia_query_route` — verified against the live EIA API v2 on 2026-05-21.
+- Skills synced to `.claude/skills/`.
+
+## Removed
+
+- Unused echo definitions (resource, app-resource, prompt, app-tool) — design is tools-only; no resources or prompts surface.

package/changelog/0.1.x/0.1.1.md

@@ -0,0 +1,42 @@
+---
+summary: "Full tool surface implementation: EIA API service layer, four domain tools, three DataCanvas dataframe tools, and a complete test suite."
+breaking: false
+security: false
+---
+
+# 0.1.1 — 2026-05-21
+
+## Added
+
+- `src/config/server-config.ts` — Zod-validated env config for `EIA_API_KEY`, `EIA_BASE_URL`, `EIA_DATASET_TTL_SECONDS`, and `EIA_DATAFRAME_DROP_ENABLED`.
+- `src/services/eia/types.ts` — EIA API v2 domain types: raw route/facet/data shapes and normalized domain objects.
+- `src/services/eia/route-cache.ts` — In-process route tree cache with Fuse.js fuzzy index; STEO's 1,469 series names included. Built lazily on first browse/search call.
+- `src/services/eia/eia-service.ts` — EIA API v2 service: route tree fetch, facet fan-out via `Promise.all`, data query with retry/rate-limit handling, and `OVER_RATE_LIMIT` → `ServiceUnavailable` classification.
+- `src/services/canvas-bridge/canvas-bridge.ts` — DataCanvas bridge: registers query result sets as DuckDB dataframes, manages per-table TTL cleanup, graceful degradation when canvas is absent.
+- `src/services/canvas-bridge/sql-gate-extras.ts` — SQL gate helpers for SELECT-only enforcement on dataframe queries.
+- `src/mcp-server/tools/definitions/browse-routes.tool.ts` — `eia_browse_routes`: walk the EIA taxonomy from root to leaf.
+- `src/mcp-server/tools/definitions/describe-route.tool.ts` — `eia_describe_route`: full leaf metadata with facet values, columns, frequencies, and date range.
+- `src/mcp-server/tools/definitions/search-routes.tool.ts` — `eia_search_routes`: Fuse.js fuzzy search across route names, descriptions, and STEO series names.
+- `src/mcp-server/tools/definitions/query-route.tool.ts` — `eia_query_route`: paginated data fetch with facet filters, date range, frequency, and DataCanvas spillover for large result sets.
+- `src/mcp-server/tools/definitions/dataframe-describe.tool.ts` — `eia_dataframe_describe`: list active DataCanvas dataframes from prior query calls.
+- `src/mcp-server/tools/definitions/dataframe-query.tool.ts` — `eia_dataframe_query`: read-only SQL SELECT against a DataCanvas dataframe by canvas ID or table name.
+- `src/mcp-server/tools/definitions/dataframe-drop.tool.ts` — `eia_dataframe_drop`: drop a DataCanvas dataframe; exposed only when `EIA_DATAFRAME_DROP_ENABLED=true` (disabled by default via `disabledTool`).
+- `tests/services/route-cache.test.ts` — Unit tests for the route-cache Fuse.js index and cache behavior.
+- `tests/tools/browse-routes.tool.test.ts` — Tests for `eia_browse_routes` (root, intermediate, leaf paths, not-found error).
+- `tests/tools/describe-route.tool.test.ts` — Tests for `eia_describe_route` (full metadata, sparse upstream, non-leaf rejection).
+- `tests/tools/search-routes.tool.test.ts` — Tests for `eia_search_routes` (match, no-match, STEO series hit).
+- `tests/tools/query-route.tool.test.ts` — Tests for `eia_query_route` (inline data, canvas spillover, rate-limit error, pagination).
+- `tests/tools/dataframe-describe.tool.test.ts` — Tests for `eia_dataframe_describe`.
+- `tests/tools/dataframe-query.tool.test.ts` — Tests for `eia_dataframe_query` (SELECT enforcement, unknown frame error).
+- `tests/tools/dataframe-drop.tool.test.ts` — Tests for `eia_dataframe_drop` (success, unknown frame error).
+- `fuse.js ^7.3.0` dependency for in-process fuzzy route search.
+
+## Changed
+
+- `src/index.ts` — Replaced echo tool scaffolding with full tool registration (`browseRoutesTool`, `describeRouteTool`, `searchRoutesTool`, `queryRouteTool`, `dataframeDescribeTool`, `dataframeQueryTool`, `dropTool`), `setup()` hook calling `initEiaApiService()` and `initCanvasBridge()`.
+- `scripts/list-skills.ts` — Updated skill listing script.
+
+## Removed
+
+- `src/mcp-server/tools/definitions/echo.tool.ts` — Placeholder echo tool replaced by domain tools.
+- `tests/tools/echo.tool.test.ts` — Echo tool tests removed with the tool.

package/changelog/0.1.x/0.1.2.md

@@ -0,0 +1,22 @@
+---
+summary: "mcp-ts-core ^0.9.5, error code semantics for domain validation, MCPB bundle support."
+breaking: false
+security: false
+---
+
+# 0.1.2 — 2026-05-23
+
+## Added
+
+- **MCPB bundle support** — `manifest.json`, `.mcpbignore`, and `bundle` / `lint:packaging` / `audit:refresh` / `publish-mcp` scripts added; `bun run bundle` produces a `.mcpb` for one-click Claude Desktop install.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.1 → ^0.9.5` — picks up `RequestContextLike` interface (0.9.3), error code refinements, and associated fixes.
+- **`zod`** `^4.4.3` added as an explicit dependency (was previously a transitive-only dep).
+- **`ctx as unknown as …` cast removed** from canvas bridge — `Context` is now directly assignable to `RequestContextLike` since 0.9.3; cast was dead code.
+- **`async` removed** from `browse-routes` handler — handler body has no `await`; spurious modifier dropped.
+- **Error code semantics** — domain validation errors in `eia_query_route` (facet validation, length checks) now throw `validationError()` instead of `invalidParams()`; aligns with framework contract for user-supplied value failures.
+- **`describe-on-fields` lint fixes** across `browse-routes`, `describe-route`, `search-routes`, `query-route`, and `dataframe-query` tool files — all Zod fields now carry `.describe()`.
+- **Skills synced** — `field-test` 2.4 → 2.5, `maintenance` 2.1 → 2.4, `polish-docs-meta` 1.8 → 2.1, `release-and-publish` 2.2 → 2.4.
+- **`devcheck.ts` updated**, `lint-packaging.ts` added to `scripts/`.

package/changelog/0.1.x/0.1.3.md

@@ -0,0 +1,17 @@
+---
+summary: "mcp-ts-core ^0.9.5 → ^0.9.6, LICENSE file, lint-packaging updates."
+breaking: false
+security: false
+---
+
+# 0.1.3 — 2026-05-23
+
+## Added
+
+- **LICENSE** — Apache-2.0 license file added to the repo root and included in the npm package.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.5 → ^0.9.6`.
+- **`scripts/lint-packaging.ts`** — updated to validate manifest name scope and `user_config` field alignment.
+- **Skills synced** — `polish-docs-meta` 2.1 → 2.2, `release-and-publish` 2.4 → 2.5.

package/changelog/0.1.x/0.1.4.md

@@ -0,0 +1,17 @@
+---
+summary: "Field-test bug fixes: route tree misclassification, ZodError on value-array columns, 4xx error codes, auto-populate data[] columns, STEO filter_hint, description normalization."
+breaking: false
+security: false
+---
+
+# 0.1.4 — 2026-05-23
+
+## Fixed
+
+- **Route tree classification** — second-level nodes were misclassified as leaves because `buildRouteTree` fetched them using only their segment `id` instead of the full path (e.g. `petroleum/gnd` instead of `gnd`). Now tracks `parentPath` through recursion and preserves the stub's `id`/`name` on merge so EIA's domain-category responses don't overwrite route segment IDs.
+- **ZodError on `data.value:[]` column format** — time-series routes that return `{ value: [] }` instead of the standard `{ colId: { alias, units } }` shape caused a Zod parse crash when normalizing data columns. `describeRoute` now filters out array entries and synthesizes a `{ id: "value", alias: "Value", units: "" }` column instead.
+- **EIA 4xx errors mapped to correct codes** — `404` responses now throw `NotFound` and `400` responses throw `ValidationError` (both non-retryable), instead of `ServiceUnavailable`. The upstream error body (`{ error: string }`) is preserved in the error message.
+- **Auto-populate `data[]` columns** — `queryRoute` omitted the `data[]` query parameter when `columns` was not specified, causing EIA to return rows without measurement values. The call now falls back to all `dataColumns` from route metadata cache when `columns` is omitted.
+- **STEO `filter_hint`** — `eia_search_routes` results for STEO series now include a `filter_hint` field (`{ seriesId: "<id>" }`) that can be passed directly as `filters` to `eia_query_route`, removing the need to parse the series ID from the description string.
+- **Route description normalization** — EIA descriptions containing embedded `\r\n` + whitespace (source-level line wrapping) are now collapsed to clean single-line strings in both the route cache and `describeRoute` output.
+- **`filters` vs `facets` cross-reference** — `eia_describe_route` facet `id` field description and `eia_query_route` `filters` parameter description now cross-reference each other by name (e.g. "use as key in the `filters` parameter of `eia_query_route`").

package/changelog/0.1.x/0.1.5.md

@@ -0,0 +1,19 @@
+---
+summary: "Pre-launch polish: code simplification, docs/metadata sync, bunfig.toml, Dockerfile labels, server.json env var coverage."
+breaking: false
+---
+
+# 0.1.5 — 2026-05-23
+
+## Changed
+
+- **`eia-service.ts`** — simplified `OVER_RATE_LIMIT` detection (extracted `parsedResponse` variable) and `dataColumns` map (extracted `col` binding); equivalent behavior.
+- **`canvas-bridge.ts`** — moved `registerAs` destructure after the `instance.query()` call to match its actual first use.
+- **`query-route.tool.ts`** — added `.describe()` to the passthrough row object in the output schema.
+- **`server.json`** — added `EIA_DATASET_TTL_SECONDS`, `EIA_DATAFRAME_DROP_ENABLED`, and `CANVAS_PROVIDER_TYPE` env var entries to both stdio and HTTP packages (were missing from the registry manifest).
+- **`Dockerfile`** — filled in `org.opencontainers.image.description` and added `org.opencontainers.image.source` label.
+- **`.env.example`** — replaced generic placeholder section with concrete EIA and Canvas env var entries.
+- **`README.md`** — added Docker badge, updated Cursor/VS Code deeplink configs to include `EIA_API_KEY` env, added `cp .env.example .env` install step, added `EIA_DATASET_TTL_SECONDS` and `EIA_DATAFRAME_DROP_ENABLED` to the configuration table.
+- **`package.json`** — removed stale `AGENTS.md` from `files[]`; added `energy-api` and `llm` keywords.
+- **`bunfig.toml`** — added with `[install] auto=fallback` and `[run] bun=true`.
+- **`CLAUDE.md`** — updated server config pattern to reflect current `datasetTtlSeconds`/`dataframeDropEnabled` schema (removed stale `canvasProvider` field).

package/changelog/0.1.x/0.1.6.md

@@ -0,0 +1,19 @@
+---
+summary: "Field-test bug fixes: error contracts, schema handling, and UX across eia_describe_route, eia_query_route, and eia_search_routes."
+breaking: false
+security: false
+---
+
+# 0.1.6 — 2026-05-23
+
+## Fixed
+
+- **`eia_describe_route` / `eia_query_route`**: `route_not_found` error now fires with contract `reason` and recovery hint when the route does not exist.
+- **`eia_query_route`**: `invalid_facet` error now fires with contract `reason` and recovery hint on a 400 from EIA; dead `invalid_facet_value` contract entry removed.
+- **`eia_query_route`**: units columns extracted to table headers (`col (unit)`) instead of repeated as `{col}-units` fields on every row.
+- **`eia_search_routes`**: description example replaced with one that resolves (`electricity retail sales by state`); weak-match label added for scores > 0.5.
+- **`eia_describe_route`**: null facet `id`/`name` values from EIA (e.g. international route) are now filtered out instead of surfaced.
+- **`eia_describe_route`**: undefined data column `alias` (e.g. crude-oil-imports route) now falls back to the column `id` instead of crashing.
+- **`eia_query_route`**: category (non-leaf) route now returns a typed `ValidationError` before hitting the EIA API.
+- **`eia_query_route`**: inverted date range (`start > end`) now returns a `no_data` validation error with a swap hint.
+- **`eia_describe_route`**: nonexistent route now returns `route_not_found` with a recovery hint pointing to `eia_browse_routes` / `eia_search_routes`.

package/changelog/0.1.x/0.1.7.md

@@ -0,0 +1,11 @@
+---
+summary: "Add @duckdb/node-api ^1.5.3-r.1 — enables DuckDB canvas provider for dataframe tools."
+breaking: false
+security: false
+---
+
+# 0.1.7 — 2026-05-23
+
+## Dependencies
+
+- `@duckdb/node-api ^1.5.3-r.1` added — provides the DuckDB runtime required by the DataCanvas canvas provider (`CANVAS_PROVIDER_TYPE=duckdb`). The three dataframe tools (`eia_dataframe_describe`, `eia_dataframe_query`, `eia_dataframe_drop`) now function end-to-end when DuckDB is enabled.

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,22 @@
+---
+summary: "Repo and package renamed from eia-mcp-server to eia-energy-mcp-server; tool names (eia_*) unchanged."
+breaking: true
+security: false
+---
+
+# 0.2.0 — 2026-05-24
+
+Package rename. All tool names (`eia_*`) and the MCP tool surface are unchanged — this is a breaking change only for npm consumers referencing the old package identifier.
+
+## Changed
+
+- **npm package** renamed from `@cyanheads/eia-mcp-server` to `@cyanheads/eia-energy-mcp-server` ([#18](https://github.com/cyanheads/eia-energy-mcp-server/issues/18)).
+- **GitHub repo** renamed from `cyanheads/eia-mcp-server` to `cyanheads/eia-energy-mcp-server`.
+- **Docker image** renamed from `ghcr.io/cyanheads/eia-mcp-server` to `ghcr.io/cyanheads/eia-energy-mcp-server`.
+- **Hosted endpoint** moving to `https://eia-energy.caseyjhand.com/mcp` (subdomain change; old `eia.caseyjhand.com` redirects during transition).
+- **MCP server name** updated to `io.github.cyanheads/eia-energy-mcp-server` in `server.json`.
+- **Tool names unchanged** — all seven `eia_*` tools retain their existing identifiers; no client-side tool renames needed.
+
+## Deprecated
+
+- `@cyanheads/eia-mcp-server` on npm — deprecated with a migration notice pointing to `@cyanheads/eia-energy-mcp-server`.

package/changelog/template.md

@@ -0,0 +1,93 @@
+---
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. 350 character cap.
+# Default short and scannable. Don't pad, don't stitch unrelated changes with
+# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
+# inside the value as a key separator and fails GitHub's strict parser.
+summary: ""
+
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
+breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+security: false
+---
+
+# <version> — YYYY-MM-DD
+
+<!--
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
+  name the symbol, state what changed, stop. Use a second sentence only when
+  it carries weight. If a bullet feels long, it is.
+
+  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
+  relevant skill), ceremonial framings ("This release introduces…",
+  backwards-compat paragraphs), file-by-file test enumerations, internal
+  implementation notes. Prefer code/symbol names over English re-explanations.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
+## Fixed
+
+-
+
+<!-- ## Security
+
+- -->

package/dist/config/server-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview EIA server-specific environment configuration. Parsed lazily on
+ * first call; validated via Zod so errors name the actual env var at fault.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodDefault<z.ZodString>;
+    datasetTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    dataframeDropEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export declare function getServerConfig(): ServerConfig;
+/** Reset for tests that need to change config. */
+export declare function _resetServerConfig(): void;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;iBAatB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/config/server-config.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview EIA server-specific environment configuration. Parsed lazily on
+ * first call; validated via Zod so errors name the actual env var at fault.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+const ServerConfigSchema = z.object({
+    apiKey: z.string().describe('EIA API key'),
+    baseUrl: z.string().url().default('https://api.eia.gov/v2').describe('EIA API base URL'),
+    datasetTtlSeconds: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(86400)
+        .describe('Per-table TTL for canvas dataframes in seconds (default 24 h)'),
+    dataframeDropEnabled: z
+        .preprocess((v) => v === 'true' || v === true, z.boolean())
+        .default(false)
+        .describe('Expose eia_dataframe_drop when true'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        apiKey: 'EIA_API_KEY',
+        baseUrl: 'EIA_BASE_URL',
+        datasetTtlSeconds: 'EIA_DATASET_TTL_SECONDS',
+        dataframeDropEnabled: 'EIA_DATAFRAME_DROP_ENABLED',
+    });
+    return _config;
+}
+/** Reset for tests that need to change config. */
+export function _resetServerConfig() {
+    _config = undefined;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACxF,iBAAiB,EAAE,CAAC,CAAC,MAAM;SACxB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,+DAA+D,CAAC;IAC5E,oBAAoB,EAAE,CAAC;SACpB,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC1D,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,qCAAqC,CAAC;CACnD,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,cAAc;QACvB,iBAAiB,EAAE,yBAAyB;QAC5C,oBAAoB,EAAE,4BAA4B;KACnD,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview eia-energy-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}