us-gov-open-data-mcp 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# US Government Open Data MCP
+
+An MCP server + TypeScript SDK for **36 U.S. government and international data APIs** — 188 tools covering economic, fiscal, health, education, energy, environment, lobbying, housing, patents, safety, banking, consumer protection, workplace safety, transportation, seismic, clinical trials, and legislative data.
+
+Works with any MCP client (VS Code Copilot, Claude Desktop, Cursor) via **stdio or HTTP Stream**. Supports **selective module loading** and standalone **SDK imports** for use without MCP.
+
+Built with [FastMCP](https://github.com/punkpeye/fastmcp). Disk-cached, rate-limited, retries with backoff.
+
+## Data Sources
+
+| API | What it covers | Auth |
+|-----|---------------|------|
+| **Treasury Fiscal Data** | 53 datasets, 181 endpoints: national debt, revenue, spending, interest rates, exchange rates, gold reserves | None |
+| **FRED** | 800K+ economic time series: GDP, CPI, unemployment, interest rates, money supply, housing, S&P 500 | `FRED_API_KEY` |
+| **BLS** | Employment by industry, wages, CPI by component, PPI, JOLTS, labor productivity | `BLS_API_KEY` (optional) |
+| **BEA** | State GDP, GDP by industry, personal income by state, national accounts (NIPA) | `BEA_API_KEY` |
+| **EIA** | Petroleum, electricity, natural gas prices; state energy profiles | `EIA_API_KEY` |
+| **Census Bureau** | Population, demographics, income, housing from ACS and Decennial Census | `CENSUS_API_KEY` |
+| **OpenFEC** | Campaign finance: candidates, committees, contributions, expenditures | `DATA_GOV_API_KEY` |
+| **Congress.gov** | Bills, members, laws, amendments, House & Senate roll call votes (1990+) | `DATA_GOV_API_KEY` |
+| **Federal Register** | Executive orders, presidential documents, rules, agency notices, document detail, 470+ agency directory | None |
+| **USAspending** | Federal contracts, grants, loans — $6T+ annually by agency, recipient, state | None |
+| **SEC EDGAR** | Company filings, XBRL financials, full-text search | `SEC_CONTACT_EMAIL` |
+| **FBI Crime Data** | Crime statistics by state, national estimates, arrests | `DATA_GOV_API_KEY` |
+| **GovInfo** | Full text of bills, laws, CBO reports, Federal Register | `DATA_GOV_API_KEY` |
+| **NOAA Climate** | Weather observations, temperature, precipitation from U.S. stations | `NOAA_API_KEY` |
+| **USDA NASS** | Crop production, livestock, farm prices, Census of Agriculture | `USDA_NASS_API_KEY` |
+| **World Bank** | International indicators: GDP, population, health spending for 200+ countries | None |
+| **CDC Health Data** | Leading causes of death, life expectancy, mortality rates, county/city health indicators (PLACES), drug overdose, obesity, disability, birth indicators, weekly death surveillance, COVID-19 — 13 tools across 12 datasets | None |
+| **NAEP (Nation's Report Card)** | Reading, math, science test scores by state, grade, race, gender, poverty — the gold standard for U.S. education measurement | None |
+| **College Scorecard** | College costs, graduation rates, post-graduation earnings, student debt, admission rates for every U.S. college | `DATA_GOV_API_KEY` |
+| **NREL (Clean Energy)** | EV charging stations, alt fuel infrastructure, electricity rates, solar resource data | `DATA_GOV_API_KEY` |
+| **FDA (OpenFDA)** | Drug adverse events (20M+ reports), drug recalls, FDA-approved drugs (Drugs@FDA), drug labels, food recalls, food adverse events (CAERS), medical device events, device recalls — 8 tools | None |
+| **EPA** | Air quality data, facility compliance/violations, UV index forecasts | None |
+| **Senate Lobbying Disclosures** | Lobbying filings, expenditures by issue, campaign contributions, individual lobbyist search — follow the money | None |
+| **Regulations.gov** | Federal rulemaking: proposed rules, final rules, public comments, regulatory dockets | `DATA_GOV_API_KEY` |
+| **USDA FoodData Central** | Nutritional data for 300K+ foods: calories, macros, vitamins, minerals for branded and reference foods | `DATA_GOV_API_KEY` |
+| **FEMA** | Disaster declarations, housing assistance, public assistance, NFIP flood claims, hazard mitigation | None |
+| **NHTSA** | Vehicle safety recalls, consumer complaints, NCAP 5-star safety ratings, VIN decoding, make/model lookup | None |
+| **CMS Provider Data** | Hospital quality ratings, nursing home inspections, home health, hospice, dialysis facility data | None |
+| **HUD** | Fair Market Rents by bedroom count, income limits by household size, county/metro area housing data | `HUD_USER_TOKEN` |
+| **USPTO PatentsView** | U.S. patent search by keyword, assignee, inventor, CPC class; inventor and assignee lookup | None |
+| **CFPB** | Consumer complaint database: 13M+ complaints against financial companies, searchable by company/product/state/issue with trend analysis | None |
+| **FDIC** | Bank data: 5,000+ insured institutions, failures since 1934, quarterly financials, branch deposits, merger history | None |
+| **DOL** | OSHA inspections/violations/accidents, WHD wage theft enforcement, weekly unemployment insurance claims (national + state) | `DOL_API_KEY` |
+| **USGS** | Earthquake events (magnitude, location, depth, tsunami risk), water resources monitoring (real-time and daily historical streamflow, water levels) from 13,000+ stations | None |
+| **ClinicalTrials.gov** | 400K+ clinical trials: search by condition, drug, sponsor, phase, status, location. Track pharma drug pipelines | None |
+| **BTS** | Bureau of Transportation Statistics: monthly transport stats (airline traffic, transit, rail, safety, fuel), border crossings at U.S. ports of entry | None |
+
+## Quick Start
+
+```bash
+npx us-gov-open-data-mcp
+```
+
+### VS Code / Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "us-gov-open-data": {
+      "command": "npx",
+      "args": ["-y", "us-gov-open-data-mcp"],
+      "env": {
+        "FRED_API_KEY": "your_key",
+        "DATA_GOV_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "us-gov-open-data": {
+      "command": "npx",
+      "args": ["-y", "us-gov-open-data-mcp"],
+      "env": {
+        "FRED_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### HTTP Stream (for web apps, remote access)
+
+```bash
+# Start on port 8080
+node dist/server.js --transport httpStream --port 8080
+
+# Or via npm script
+npm run start:http
+```
+
+The HTTP Stream endpoint will be at `http://localhost:8080/mcp`. Works with any MCP client that supports HTTP transport.
+
+### Selective Module Loading
+
+Load only the modules you need for faster startup and smaller tool lists:
+
+```bash
+# Via CLI flag
+node dist/server.js --modules fred,treasury,congress
+
+# Via environment variable
+MODULES=fred,bls,treasury node dist/server.js
+
+# Combine with HTTP transport
+node dist/server.js --modules fred,treasury --transport httpStream --port 8080
+```
+
+Available module names: `treasury`, `fred`, `bls`, `bea`, `eia`, `census`, `fec`, `congress`, `federal-register`, `usaspending`, `sec`, `fbi`, `govinfo`, `noaa`, `usda-nass`, `world-bank`, `cdc`, `naep`, `college-scorecard`, `nrel`, `fda`, `epa`, `senate-lobbying`, `regulations`, `usda-fooddata`, `fema`, `nhtsa`, `cms`, `hud`, `uspto`, `cfpb`, `fdic`, `dol`, `usgs`, `clinical-trials`, `bts`
+
+## API Keys
+
+18 APIs require **no key at all** (Treasury, Federal Register, USAspending, World Bank, CDC, FDA, EPA, NAEP, Senate Lobbying, FEMA, NHTSA, CMS, USPTO, CFPB, FDIC, USGS, ClinicalTrials.gov, BTS). The rest need free keys — most take under a minute to get:
+
+| Key | Where to get it | Used by |
+|-----|----------------|---------|
+| `DATA_GOV_API_KEY` | [api.data.gov/signup](https://api.data.gov/signup/) | Congress, FEC, FBI, GovInfo, College Scorecard, NREL, Regulations.gov, USDA FoodData |
+| `FRED_API_KEY` | [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) | FRED |
+| `CENSUS_API_KEY` | [api.census.gov/data/key_signup.html](https://api.census.gov/data/key_signup.html) | Census |
+| `BLS_API_KEY` | [bls.gov/developers](https://www.bls.gov/developers/) | BLS (optional — works without, higher limits with) |
+| `BEA_API_KEY` | [apps.bea.gov/API/signup](https://apps.bea.gov/API/signup/) | BEA |
+| `EIA_API_KEY` | [eia.gov/opendata/register.php](https://www.eia.gov/opendata/register.php) | EIA |
+| `NOAA_API_KEY` | [ncei.noaa.gov/cdo-web/token](https://www.ncei.noaa.gov/cdo-web/token) | NOAA |
+| `USDA_NASS_API_KEY` | [quickstats.nass.usda.gov/api](https://quickstats.nass.usda.gov/api) | USDA NASS |
+| `HUD_USER_TOKEN` | [huduser.gov/hudapi/public/register](https://www.huduser.gov/hudapi/public/register) | HUD |
+| `SEC_CONTACT_EMAIL` | Any valid email | SEC EDGAR |
+| `DOL_API_KEY` | [data.dol.gov/registration](https://data.dol.gov/registration) | DOL (OSHA, WHD, UI Claims) |
+
+Set keys via environment variables or a `.env` file in the project root.
+
+## Using as a TypeScript SDK
+
+Every API is importable as a standalone typed client — no MCP server required:
+
+```typescript
+// Individual module imports
+import { getObservations } from "us-gov-open-data-mcp/sdk/fred";
+import { getIndicator } from "us-gov-open-data-mcp/sdk/world-bank";
+import { getLeadingCausesOfDeath } from "us-gov-open-data-mcp/sdk/cdc";
+import { searchBills } from "us-gov-open-data-mcp/sdk/congress";
+
+// Or barrel import everything
+import * as sdk from "us-gov-open-data-mcp/sdk";
+const gdp = await sdk.fred.getObservations("GDP", { sort: "desc", limit: 5 });
+```
+
+```typescript
+// FRED
+const gdp = await getObservations("GDP", { sort: "desc", limit: 5 });
+console.log(gdp.observations); // [{ date: "2025-10-01", value: "31490.07" }, ...]
+
+// World Bank — compare U.S. to Germany
+const health = await getIndicator("SH.XPD.CHEX.PC.CD", { country: "US;DE", dateRange: "2015:2023" });
+
+// CDC
+const deaths = await getLeadingCausesOfDeath({ state: "California", year: 2017 });
+```
+
+All SDK functions include disk-backed caching, retry with exponential backoff, and token-bucket rate limiting. See [docs/sdk.md](docs/sdk.md) for the full API reference.
+
+## Architecture
+
+```
+src/
+  client.ts              # createClient() factory — cache, retry, rate-limit
+  server.ts              # FastMCP bootstrap — stdio + HTTP, selective loading
+  instructions.ts        # Cross-referencing guide for MCP clients
+  sdk/
+    index.ts             # Barrel export for all SDK modules
+    fred.ts, bls.ts, ... # Typed API clients (no MCP dependency)
+  modules/
+    fred.ts, bls.ts, ... # MCP tool definitions + metadata
+```
+
+Each API is 2 files:
+- **`sdk/*.ts`** — typed async functions, usable anywhere (no MCP/Zod dependency)
+- **`modules/*.ts`** — MCP tool definitions wrapping the SDK, with metadata for client instructions
+
+Adding a new API: create `sdk/new-api.ts` + `modules/new-api.ts`, add 2 lines to `server.ts`. See [docs/adding-modules.md](docs/adding-modules.md).
+
+## Documentation
+
+- [SDK API Reference](docs/sdk.md) — all exported functions and types
+- [Adding New Modules](docs/adding-modules.md) — how to add a new API
+- [Architecture](docs/architecture.md) — how the system works
+
+## Disclaimer
+
+This project was built with the assistance of AI tools. All data is sourced from official U.S. government and international APIs — the server does not generate, modify, or editorialize any data. It returns raw results from federal databases exactly as provided.
+
+**Important:**
+- Data accuracy depends on the upstream government APIs. Numbers may lag days to years behind reality depending on the source.
+- Correlation does not imply causation. Cross-referencing data sources (e.g., campaign finance + legislative votes) shows documented patterns, not proven cause-and-effect.
+- This tool is for research and informational purposes. It is not legal, financial, medical, or policy advice.
+- API rate limits and availability vary. Some endpoints may be temporarily unavailable or return incomplete data.
+- The example analyses in the `examples/` folder demonstrate the server's capabilities and should not be treated as investigative conclusions.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lightweight API client factory with caching, retry, and rate limiting.
+ *
+ * Instead of an abstract class with 7 virtual methods, this uses a config
+ * object to create a client. Each module calls createClient() once.
+ *
+ * Features:
+ *   - Disk-backed TTL cache (survives MCP server restarts)
+ *   - Timeout (30s default)
+ *   - Retry with exponential backoff (429, 502, 503, 504)
+ *   - Token-bucket rate limiting
+ *   - Auth via query param, header, or request body
+ */
+export interface ClientConfig {
+    baseUrl: string;
+    name: string;
+    /** Auth configuration — how to attach the API key to requests */
+    auth?: {
+        /** Where to inject the key */
+        type: "query" | "header" | "body";
+        /** The param/header name (e.g. "api_key", "Authorization", "registrationkey") */
+        key: string;
+        /** Env var to read the key from */
+        envVar: string;
+        /** Extra static params (e.g. { file_type: "json" } for FRED) */
+        extraParams?: Record<string, string>;
+        /** For header auth: prefix like "Bearer " */
+        prefix?: string;
+    };
+    /** Rate limiting */
+    rateLimit?: {
+        perSecond: number;
+        burst: number;
+    };
+    /** Default headers on every request (e.g. User-Agent for SEC) */
+    defaultHeaders?: Record<string, string>;
+    /** Cache TTL in ms (default: 5 min). Government data often updates daily/weekly — set
+     *  higher for infrequent data: 1 hour = 3_600_000, 1 day = 86_400_000. Set 0 to disable. */
+    cacheTtlMs?: number;
+    /** Timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Custom error detector — some APIs return 200 OK with errors in the body */
+    checkError?: (data: unknown) => string | null;
+}
+/** Param values: string, number, string[] (for repeated keys like facets[series][]), or undefined to skip */
+export type ParamValue = string | number | string[] | undefined;
+export type Params = Record<string, ParamValue>;
+export interface ApiClient {
+    get<T = unknown>(path: string, params?: Params): Promise<T>;
+    post<T = unknown>(path: string, body?: Record<string, unknown>, params?: Params): Promise<T>;
+    clearCache(): void;
+}
+export declare function createClient(config: ClientConfig): ApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IAEb,iEAAiE;IACjE,IAAI,CAAC,EAAE;QACL,8BAA8B;QAC9B,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;QAClC,iFAAiF;QACjF,GAAG,EAAE,MAAM,CAAC;QACZ,mCAAmC;QACnC,MAAM,EAAE,MAAM,CAAC;QACf,gEAAgE;QAChE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACrC,6CAA6C;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,oBAAoB;IACpB,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAEjD,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;gGAC4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;CAC/C;AAED,6GAA6G;AAC7G,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7F,UAAU,IAAI,IAAI,CAAC;CACpB;AA8RD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CA0H5D"}

package/dist/client.js

@@ -0,0 +1,388 @@
+/**
+ * Lightweight API client factory with caching, retry, and rate limiting.
+ *
+ * Instead of an abstract class with 7 virtual methods, this uses a config
+ * object to create a client. Each module calls createClient() once.
+ *
+ * Features:
+ *   - Disk-backed TTL cache (survives MCP server restarts)
+ *   - Timeout (30s default)
+ *   - Retry with exponential backoff (429, 502, 503, 504)
+ *   - Token-bucket rate limiting
+ *   - Auth via query param, header, or request body
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+// ─── Token Bucket Rate Limiter ───────────────────────────────────────
+class TokenBucket {
+    max;
+    rate;
+    tokens;
+    lastRefill;
+    constructor(max, rate) {
+        this.max = max;
+        this.rate = rate;
+        this.tokens = max;
+        this.lastRefill = Date.now();
+    }
+    async acquire() {
+        const now = Date.now();
+        this.tokens = Math.min(this.max, this.tokens + ((now - this.lastRefill) / 1000) * this.rate);
+        this.lastRefill = now;
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        const waitMs = Math.ceil(((1 - this.tokens) / this.rate) * 1000);
+        await new Promise(r => setTimeout(r, waitMs));
+        this.tokens = 0;
+    }
+}
+// ─── Disk-backed TTL Cache ────────────────────────────────────────────
+//
+// Single consolidated JSON file shared by all modules. Lazy-loaded on
+// first cache miss. LRU eviction per module keeps memory bounded.
+// Async writes don't block the event loop. Global write coalescing
+// batches all module updates into one disk write.
+function getCacheDir() {
+    const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+    const dir = join(base, "us-gov-open-data-mcp");
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    catch {
+        const fallback = join(tmpdir(), "us-gov-open-data-mcp");
+        if (!existsSync(fallback))
+            mkdirSync(fallback, { recursive: true });
+        return fallback;
+    }
+}
+const CACHE_DIR = getCacheDir();
+const CACHE_FILE = join(CACHE_DIR, "cache.json");
+const MAX_ENTRIES_PER_MODULE = 200;
+// ─── Global disk store (shared by all DiskCache instances) ───────────
+let _globalLoaded = false;
+let _globalDirty = false;
+let _globalWriteTimer;
+/** namespace → key → entry */
+const _globalStore = new Map();
+function loadGlobal() {
+    if (_globalLoaded)
+        return;
+    _globalLoaded = true;
+    try {
+        if (!existsSync(CACHE_FILE)) {
+            // Migrate: try loading legacy per-module files
+            migrateLegacyFiles();
+            return;
+        }
+        const raw = JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+        const now = Date.now();
+        let totalLoaded = 0;
+        for (const [ns, entries] of Object.entries(raw)) {
+            const map = new Map();
+            for (const [key, entry] of Object.entries(entries)) {
+                if (entry.expires > now) {
+                    map.set(key, entry);
+                    totalLoaded++;
+                }
+            }
+            if (map.size > 0)
+                _globalStore.set(ns, map);
+        }
+        if (totalLoaded > 0 && process.env.DEBUG_CACHE) {
+            console.error(`Cache: loaded ${totalLoaded} entries from disk (${_globalStore.size} modules)`);
+        }
+    }
+    catch {
+        // Corrupted — start fresh
+    }
+}
+/** One-time migration from the old per-module *.json files to the consolidated cache.json */
+function migrateLegacyFiles() {
+    try {
+        const { readdirSync, unlinkSync } = require("node:fs");
+        const files = readdirSync(CACHE_DIR).filter((f) => f.endsWith(".json") && f !== "cache.json");
+        if (files.length === 0)
+            return;
+        const now = Date.now();
+        let migrated = 0;
+        for (const file of files) {
+            try {
+                const ns = file.replace(/\.json$/, "");
+                const raw = JSON.parse(readFileSync(join(CACHE_DIR, file), "utf-8"));
+                const map = new Map();
+                for (const [key, entry] of Object.entries(raw)) {
+                    if (entry.expires > now) {
+                        // Add lastAccess if missing (legacy entries don't have it)
+                        if (!entry.lastAccess)
+                            entry.lastAccess = now;
+                        map.set(key, entry);
+                        migrated++;
+                    }
+                }
+                if (map.size > 0)
+                    _globalStore.set(ns, map);
+                unlinkSync(join(CACHE_DIR, file)); // Remove legacy file
+            }
+            catch {
+                // Skip corrupt file
+            }
+        }
+        if (migrated > 0) {
+            _globalDirty = true;
+            scheduleGlobalWrite();
+            if (process.env.DEBUG_CACHE) {
+                console.error(`Cache: migrated ${migrated} entries from ${files.length} legacy files`);
+            }
+        }
+    }
+    catch {
+        // Migration is best-effort
+    }
+}
+function scheduleGlobalWrite() {
+    if (_globalWriteTimer)
+        return;
+    _globalWriteTimer = setTimeout(() => {
+        _globalWriteTimer = undefined;
+        if (!_globalDirty)
+            return;
+        _globalDirty = false;
+        const now = Date.now();
+        const obj = {};
+        for (const [ns, map] of _globalStore) {
+            const entries = {};
+            for (const [key, entry] of map) {
+                if (entry.expires > now)
+                    entries[key] = entry;
+            }
+            if (Object.keys(entries).length > 0)
+                obj[ns] = entries;
+        }
+        // Async write — non-blocking
+        writeFile(CACHE_FILE, JSON.stringify(obj), "utf-8").catch(() => { });
+    }, 2000);
+    if (typeof _globalWriteTimer === "object" && "unref" in _globalWriteTimer) {
+        _globalWriteTimer.unref();
+    }
+}
+// ─── Per-module cache interface ──────────────────────────────────────
+class DiskCache {
+    ns;
+    ttlMs;
+    constructor(ttlMs, name) {
+        this.ttlMs = ttlMs;
+        this.ns = name;
+    }
+    getMap() {
+        loadGlobal(); // Lazy — only reads disk on first access
+        let map = _globalStore.get(this.ns);
+        if (!map) {
+            map = new Map();
+            _globalStore.set(this.ns, map);
+        }
+        return map;
+    }
+    get(key) {
+        const map = this.getMap();
+        const entry = map.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expires) {
+            map.delete(key);
+            _globalDirty = true;
+            scheduleGlobalWrite();
+            return undefined;
+        }
+        // Update last access for LRU
+        entry.lastAccess = Date.now();
+        return entry.data;
+    }
+    set(key, data) {
+        if (this.ttlMs <= 0)
+            return;
+        const map = this.getMap();
+        // LRU eviction if at capacity
+        if (map.size >= MAX_ENTRIES_PER_MODULE && !map.has(key)) {
+            let oldestKey;
+            let oldestAccess = Infinity;
+            for (const [k, e] of map) {
+                const access = e.lastAccess ?? e.expires - this.ttlMs;
+                if (access < oldestAccess) {
+                    oldestAccess = access;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey)
+                map.delete(oldestKey);
+        }
+        const now = Date.now();
+        map.set(key, { data, expires: now + this.ttlMs, lastAccess: now });
+        _globalDirty = true;
+        scheduleGlobalWrite();
+    }
+    clear() {
+        _globalStore.delete(this.ns);
+        _globalDirty = true;
+        scheduleGlobalWrite();
+    }
+    get size() {
+        const map = _globalStore.get(this.ns);
+        if (!map)
+            return 0;
+        const now = Date.now();
+        let count = 0;
+        for (const entry of map.values()) {
+            if (now <= entry.expires)
+                count++;
+        }
+        return count;
+    }
+}
+// ─── Fetch with timeout ──────────────────────────────────────────────
+async function fetchTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ─── Retry logic ─────────────────────────────────────────────────────
+const RETRYABLE = [429, 502, 503, 504];
+async function fetchRetry(url, init, timeoutMs, limiter, name, maxRetries = 2) {
+    let lastErr = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        await limiter.acquire();
+        try {
+            const res = await fetchTimeout(url, init, timeoutMs);
+            if (RETRYABLE.includes(res.status) && attempt < maxRetries) {
+                const retryAfter = res.headers.get("Retry-After");
+                const delay = retryAfter ? (+retryAfter || 1) * 1000 : 1000 * 2 ** attempt;
+                console.error(`${name}: HTTP ${res.status}, retry in ${delay}ms (${attempt + 1}/${maxRetries})`);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            return res;
+        }
+        catch (e) {
+            lastErr = e instanceof Error ? e : new Error(String(e));
+            if (attempt < maxRetries) {
+                const delay = 1000 * 2 ** attempt;
+                console.error(`${name}: ${lastErr.message}, retry in ${delay}ms (${attempt + 1}/${maxRetries})`);
+                await new Promise(r => setTimeout(r, delay));
+            }
+        }
+    }
+    throw lastErr ?? new Error("Request failed");
+}
+// ─── Client Factory ──────────────────────────────────────────────────
+export function createClient(config) {
+    const { baseUrl, name, auth, defaultHeaders = {}, cacheTtlMs = 5 * 60 * 1000, timeoutMs = 30_000, checkError, } = config;
+    const rl = config.rateLimit ?? { perSecond: 5, burst: 10 };
+    const limiter = new TokenBucket(rl.burst, rl.perSecond);
+    const cache = new DiskCache(cacheTtlMs, name);
+    function getApiKey() {
+        return auth ? process.env[auth.envVar] : undefined;
+    }
+    function buildUrl(path, params) {
+        const parts = [];
+        // Auth via query param
+        if (auth?.type === "query") {
+            const key = getApiKey();
+            if (key)
+                parts.push(`${auth.key}=${encodeURIComponent(key)}`);
+            if (auth.extraParams) {
+                for (const [k, v] of Object.entries(auth.extraParams))
+                    parts.push(`${k}=${encodeURIComponent(v)}`);
+            }
+        }
+        // User params — supports string, number, and string[] (repeated keys)
+        // Keys are NOT encoded — preserves bracket syntax like page[number], facets[series][]
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v === undefined || v === "")
+                    continue;
+                if (Array.isArray(v)) {
+                    for (const item of v)
+                        parts.push(`${k}=${encodeURIComponent(String(item))}`);
+                }
+                else {
+                    parts.push(`${k}=${encodeURIComponent(String(v))}`);
+                }
+            }
+        }
+        const p = path.startsWith("/") ? path : `/${path}`;
+        return parts.length ? `${baseUrl}${p}?${parts.join("&")}` : `${baseUrl}${p}`;
+    }
+    function buildHeaders(extra) {
+        const h = { ...defaultHeaders, ...extra };
+        if (auth?.type === "header") {
+            const key = getApiKey();
+            if (key)
+                h[auth.key] = (auth.prefix ?? "") + key;
+        }
+        return h;
+    }
+    async function request(url, init) {
+        // Check cache
+        const cacheKey = init?.body ? `${url}|${init.body}` : url;
+        const cached = cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const res = await fetchRetry(url, init, timeoutMs, limiter, name);
+        if (!res.ok) {
+            const body = await res.text();
+            // Friendly error for auth failures when API key is missing
+            if ((res.status === 401 || res.status === 403) && auth && !getApiKey()) {
+                throw new Error(`${name}: API key required (HTTP ${res.status}). ` +
+                    `Set the ${auth.envVar} environment variable in your .env file or MCP config.`);
+            }
+            throw new Error(`${name}: HTTP ${res.status} — ${body || res.statusText}`);
+        }
+        const data = await res.json();
+        // Check for API-level errors in body
+        if (checkError) {
+            const err = checkError(data);
+            if (err)
+                throw new Error(`${name}: ${err}`);
+        }
+        cache.set(cacheKey, data);
+        return data;
+    }
+    return {
+        async get(path, params) {
+            const url = buildUrl(path, params);
+            const headers = buildHeaders();
+            return request(url, Object.keys(headers).length ? { headers } : undefined);
+        },
+        async post(path, body, params) {
+            const url = buildUrl(path, params);
+            const headers = buildHeaders({ "Content-Type": "application/json" });
+            // Auth via body (e.g. BLS)
+            const finalBody = { ...body };
+            if (auth?.type === "body") {
+                const key = getApiKey();
+                if (key) {
+                    finalBody[auth.key] = key;
+                    if (auth.extraParams)
+                        Object.assign(finalBody, auth.extraParams);
+                }
+            }
+            return request(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(finalBody),
+            });
+        },
+        clearCache() { cache.clear(); },
+    };
+}
+//# sourceMappingURL=client.js.map