us-gov-open-data-mcp 1.0.1 → 1.1.0

package/README.md

@@ -1,64 +1,32 @@
+<div align="center">
+
 # US Government Open Data MCP
 
-An MCP server + TypeScript SDK for **37 U.S. government and international data APIs** — 198 tools covering economic, fiscal, health, education, energy, environment, lobbying, housing, patents, safety, banking, consumer protection, workplace safety, transportation, seismic, clinical trials, pharma payments, and legislative data.
+**MCP Server + TypeScript SDK for 39 U.S. Government APIs**
 
-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.
+[![npm version](https://img.shields.io/npm/v/us-gov-open-data-mcp)](https://www.npmjs.com/package/us-gov-open-data-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/us-gov-open-data-mcp)](https://www.npmjs.com/package/us-gov-open-data-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Built with [FastMCP](https://github.com/punkpeye/fastmcp). Disk-cached, rate-limited, retries with backoff.
+219 tools covering economic, fiscal, health, education, energy, environment, lobbying, housing, patents, safety, banking, consumer protection, workplace safety, transportation, seismic, clinical trials, pharma payments, research funding, and legislative data.
 
-I did collapse all older commits into a single commit hence the large initial commit. This was to consolidate as well as get rid of many old files that were no longer relevant to the project when I made it public.
+**21 APIs require no key** · The rest use free keys that take under a minute to get
 
-## Data Sources
+[Getting Started](https://lzinga.github.io/us-gov-open-data-mcp/guide/getting-started) · [API Reference](https://lzinga.github.io/us-gov-open-data-mcp/api/) · [Documentation](https://lzinga.github.io/us-gov-open-data-mcp/)
+
+</div>
 
-| 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` |
-| **Open Payments** | CMS Sunshine Act data: 15M+ payments/year from pharma/device companies to doctors. Search by company, doctor, state, specialty | None |
-| **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
 
+### MCP Server
+
 ```bash
 npx us-gov-open-data-mcp
 ```
 
-### VS Code / Copilot
-
-Add to `.vscode/mcp.json`:
+Add to `.vscode/mcp.json` for VS Code / Copilot:
 
 ```json
 {
@@ -75,139 +43,57 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
-### 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)
+### TypeScript SDK
 
 ```bash
-# Start on port 8080
-node dist/server.js --transport httpStream --port 8080
-
-# Or via npm script
-npm run start:http
+npm install us-gov-open-data-mcp
 ```
 
-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`, `open-payments`
-
-## API Keys
-
-19 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, Open Payments). 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
+No MCP server required. All functions include caching, retry, and rate limiting.
 
-```
-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
-```
+## Documentation
 
-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
+Full documentation at **[lzinga.github.io/us-gov-open-data-mcp](https://lzinga.github.io/us-gov-open-data-mcp/)**
 
-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).
+| | |
+|---|---|
+| [Getting Started](https://lzinga.github.io/us-gov-open-data-mcp/guide/getting-started) | MCP setup, SDK install, client configs |
+| [API Keys](https://lzinga.github.io/us-gov-open-data-mcp/guide/api-keys) | Which APIs need keys, where to get them |
+| [Data Sources](https://lzinga.github.io/us-gov-open-data-mcp/guide/data-sources) | All 39 APIs grouped by category |
+| [API Reference](https://lzinga.github.io/us-gov-open-data-mcp/api/) | Auto-generated from TypeScript — every function and type |
+| [Examples](https://lzinga.github.io/us-gov-open-data-mcp/guide/sdk-usage) | SDK code, MCP prompts, analysis showcases |
+| [Architecture](https://lzinga.github.io/us-gov-open-data-mcp/guide/architecture) | How the system works |
+| [Adding Modules](https://lzinga.github.io/us-gov-open-data-mcp/guide/adding-modules) | Add a new API — just create a folder |
 
-## Documentation
+## Data Sources
 
-- [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
+| Category | APIs |
+|----------|------|
+| **Economic** | Treasury, FRED, BLS, BEA, EIA |
+| **Legislative** | Congress.gov, Federal Register, GovInfo, Regulations.gov |
+| **Financial** | FEC, Senate Lobbying, SEC, FDIC, CFPB |
+| **Spending** | USAspending, Open Payments |
+| **Health & Safety** | CDC, FDA, CMS, ClinicalTrials.gov, NIH, NHTSA, DOL |
+| **Environment** | EPA, NOAA, NREL, USGS |
+| **Justice** | FBI Crime Data, DOJ News |
+| **Education** | NAEP, College Scorecard, USPTO |
+| **Demographics** | Census, HUD, FEMA |
+| **Other** | BTS, USDA NASS, USDA FoodData, World Bank |
 
 ## 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.
+This project integrates **30+ government APIs**, many of which have large, complex, or inconsistently documented schemas. AI is used as a tool throughout this project to help parse API documentation, generate type definitions, and scaffold tool implementations — making it possible to cover this much surface area and get people access to government data faster than would otherwise be feasible. While every effort has been made to ensure accuracy, some endpoints may return unexpected results, have incomplete parameter coverage, or behave differently than documented.
+
+This is a community-driven effort — if you find something that's broken or could be improved, **please open an issue or submit a PR**. Contributions that fix edge cases, improve schema accuracy, or expand coverage are especially welcome. The goal is to make U.S. government data as accessible and reliable as possible, together.
 
-**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.
+All data is sourced from official U.S. government and international APIs — the server does not generate, modify, or editorialize any data.
 
 ## License
 

package/dist/apis/bea/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * bea API module.
+ */
+import { clearCache } from "./sdk.js";
+declare const _default: {
+    tools: import("fastmcp").Tool<any, any>[];
+    clearCache: typeof clearCache;
+    name: string;
+    displayName: string;
+    category: string;
+    description: string;
+    auth: {
+        envVar: string;
+        signup: string;
+    };
+    workflow: string;
+    tips: string;
+    reference: {
+        nipaTables: {
+            readonly T10101: "Real GDP percent change";
+            readonly T10105: "Nominal GDP";
+            readonly T10106: "Real GDP (chained dollars)";
+            readonly T10111: "GDP percent change contributions";
+            readonly T20100: "Personal income and its disposition";
+            readonly T20600: "Personal income (monthly)";
+            readonly T30100: "Government receipts and expenditures";
+            readonly T30200: "Federal government receipts and expenditures";
+            readonly T30300: "State/local government receipts and expenditures";
+        };
+        gdpIndustryTables: {
+            readonly 1: "Value added by industry";
+            readonly 5: "Contributions to percent change in real GDP";
+            readonly 6: "Value added as percentage of GDP";
+            readonly 25: "Real value added by industry";
+        };
+        regionalTables: {
+            readonly SAGDP1: "State annual GDP summary";
+            readonly SAGDP9: "Real GDP by state";
+            readonly SQGDP1: "State quarterly GDP summary";
+            readonly SAINC1: "Personal income, population, per capita income";
+            readonly SAINC3: "Per capita personal income";
+            readonly SAINC4: "Personal income by major component";
+            readonly SAINC5N: "Personal income by NAICS industry";
+            readonly SAINC30: "Economic profile";
+        };
+        docs: {
+            "User Guide": string;
+            "Developer Page": string;
+            "Sign Up": string;
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/apis/bea/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/apis/bea/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEtC,wBAAkE"}

package/dist/apis/bea/index.js

@@ -0,0 +1,8 @@
+/**
+ * bea API module.
+ */
+import meta from "./meta.js";
+import { tools } from "./tools.js";
+import { clearCache } from "./sdk.js";
+export default { ...meta, tools, clearCache };
+//# sourceMappingURL=index.js.map

package/dist/apis/bea/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/apis/bea/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,eAAe,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,EAAsB,CAAC"}

package/dist/apis/bea/meta.d.ts

@@ -0,0 +1,51 @@
+/**
+ * bea module metadata.
+ */
+declare const _default: {
+    name: string;
+    displayName: string;
+    category: string;
+    description: string;
+    auth: {
+        envVar: string;
+        signup: string;
+    };
+    workflow: string;
+    tips: string;
+    reference: {
+        nipaTables: {
+            readonly T10101: "Real GDP percent change";
+            readonly T10105: "Nominal GDP";
+            readonly T10106: "Real GDP (chained dollars)";
+            readonly T10111: "GDP percent change contributions";
+            readonly T20100: "Personal income and its disposition";
+            readonly T20600: "Personal income (monthly)";
+            readonly T30100: "Government receipts and expenditures";
+            readonly T30200: "Federal government receipts and expenditures";
+            readonly T30300: "State/local government receipts and expenditures";
+        };
+        gdpIndustryTables: {
+            readonly 1: "Value added by industry";
+            readonly 5: "Contributions to percent change in real GDP";
+            readonly 6: "Value added as percentage of GDP";
+            readonly 25: "Real value added by industry";
+        };
+        regionalTables: {
+            readonly SAGDP1: "State annual GDP summary";
+            readonly SAGDP9: "Real GDP by state";
+            readonly SQGDP1: "State quarterly GDP summary";
+            readonly SAINC1: "Personal income, population, per capita income";
+            readonly SAINC3: "Per capita personal income";
+            readonly SAINC4: "Personal income by major component";
+            readonly SAINC5N: "Personal income by NAICS industry";
+            readonly SAINC30: "Economic profile";
+        };
+        docs: {
+            "User Guide": string;
+            "Developer Page": string;
+            "Sign Up": string;
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=meta.d.ts.map

package/dist/apis/bea/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../../src/apis/bea/meta.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKH,wBAqBuB"}

package/dist/apis/bea/meta.js

@@ -0,0 +1,24 @@
+/**
+ * bea module metadata.
+ */
+import { nipaTables, gdpIndustryTables, regionalTables } from "./sdk.js";
+export default {
+    name: "bea",
+    displayName: "Bureau of Economic Analysis",
+    category: "Economic",
+    description: "U.S. economic statistics: GDP (national/state/industry), personal income, international transactions, fixed assets, multinational enterprises, input-output tables, and more. Covers NIPA, Regional, GDPbyIndustry, ITA, IIP, MNE, FixedAssets, IntlServTrade, InputOutput datasets.",
+    auth: { envVar: "BEA_API_KEY", signup: "https://apps.bea.gov/API/signup/" },
+    workflow: "Use bea_dataset_info to discover datasets/parameters/valid values → then call the appropriate dataset tool (bea_gdp_national, bea_gdp_by_state, etc.)",
+    tips: "Key advantages: state-level GDP and income, GDP by NAICS industry, international transactions/investment positions, fixed assets, input-output tables. Rate limit: 100 req/min with 1-hour lockout if exceeded. Use 'LAST5' or specific years instead of 'ALL' to limit data volume.",
+    reference: {
+        nipaTables,
+        gdpIndustryTables,
+        regionalTables,
+        docs: {
+            "User Guide": "https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf",
+            "Developer Page": "https://apps.bea.gov/developers/",
+            "Sign Up": "https://apps.bea.gov/API/signup/",
+        },
+    },
+};
+//# sourceMappingURL=meta.js.map

package/dist/apis/bea/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../../src/apis/bea/meta.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGzE,eAAe;IACb,IAAI,EAAE,KAAK;IACX,WAAW,EAAE,6BAA6B;IAC1C,QAAQ,EAAE,UAAU;IACpB,WAAW,EACT,sRAAsR;IACxR,IAAI,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kCAAkC,EAAE;IAC3E,QAAQ,EACN,uJAAuJ;IACzJ,IAAI,EACF,sRAAsR;IACxR,SAAS,EAAE;QACT,UAAU;QACV,iBAAiB;QACjB,cAAc;QACd,IAAI,EAAE;YACJ,YAAY,EAAE,kEAAkE;YAChF,gBAAgB,EAAE,kCAAkC;YACpD,SAAS,EAAE,kCAAkC;SAC9C;KACF;CACmB,CAAC"}

package/dist/apis/bea/sdk.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @module BEA — Bureau of Economic Analysis
+ *
+ * Typed API client for BEA's economic statistics: GDP, personal income,
+ * international transactions, fixed assets, and industry accounts.
+ *
+ * Standalone — no MCP server required. Usage:
+ *
+ *   import { getNationalGdp, getGdpByState } from "us-gov-open-data-mcp/sdk/bea";
+ *
+ *   const gdp = await getNationalGdp({ year: "2023" });
+ *   console.log(gdp.series);
+ *
+ * Requires `BEA_API_KEY` env var. Register at {@link https://apps.bea.gov/API/signup/}.
+ * API docs: {@link https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf}.
+ */
+import type { BeaNationalGdpResult, BeaStateGdpResult, BeaPersonalIncomeResult, BeaIndustryGdpResult, BeaDatasetInfo, BeaParameterInfo, BeaParamValue, BeaGenericResult, BeaItaResult, BeaIipResult, BeaIntlServTradeResult } from "./types.js";
+/** NIPA table codes — use as `tableName` in getNationalGdp(). */
+export declare const nipaTables: {
+    readonly T10101: "Real GDP percent change";
+    readonly T10105: "Nominal GDP";
+    readonly T10106: "Real GDP (chained dollars)";
+    readonly T10111: "GDP percent change contributions";
+    readonly T20100: "Personal income and its disposition";
+    readonly T20600: "Personal income (monthly)";
+    readonly T30100: "Government receipts and expenditures";
+    readonly T30200: "Federal government receipts and expenditures";
+    readonly T30300: "State/local government receipts and expenditures";
+};
+/** GDP by industry table IDs — use as `tableId` in getGdpByIndustry(). */
+export declare const gdpIndustryTables: {
+    readonly 1: "Value added by industry";
+    readonly 5: "Contributions to percent change in real GDP";
+    readonly 6: "Value added as percentage of GDP";
+    readonly 25: "Real value added by industry";
+};
+/** BEA Regional table codes — use as `tableName` in getGdpByState() and getPersonalIncome(). */
+export declare const regionalTables: {
+    readonly SAGDP1: "State annual GDP summary";
+    readonly SAGDP9: "Real GDP by state";
+    readonly SQGDP1: "State quarterly GDP summary";
+    readonly SAINC1: "Personal income, population, per capita income";
+    readonly SAINC3: "Per capita personal income";
+    readonly SAINC4: "Personal income by major component";
+    readonly SAINC5N: "Personal income by NAICS industry";
+    readonly SAINC30: "Economic profile";
+};
+/** List all BEA datasets. */
+export declare function getDatasetList(): Promise<BeaDatasetInfo[]>;
+/** List parameters for a dataset. */
+export declare function getParameterList(datasetName: string): Promise<BeaParameterInfo[]>;
+/** Get valid values for a parameter. */
+export declare function getParameterValues(datasetName: string, parameterName: string): Promise<BeaParamValue[]>;
+/** Get filtered parameter values. Not all datasets support this; Regional is the primary one. */
+export declare function getParameterValuesFiltered(datasetName: string, targetParameter: string, filters: Record<string, string>): Promise<BeaParamValue[]>;
+/** Get national GDP data from NIPA tables. */
+export declare function getNationalGdp(opts?: {
+    /** NIPA table (default: "T10101"). See nipaTables in types.ts. */
+    tableName?: string;
+    /** A=annual, Q=quarterly, M=monthly. Multiple: "A,Q". */
+    frequency?: string;
+    /** Year(s) or special: "LAST5", "LAST10", "ALL", "X", or comma-separated like "2020,2021". */
+    year?: string;
+}): Promise<BeaNationalGdpResult>;
+/** Get GDP by state from BEA Regional dataset. */
+export declare function getGdpByState(opts?: {
+    /** Regional table (default: "SAGDP1"). See regionalTables in types.ts. */
+    tableName?: string;
+    /** "STATE", "COUNTY", "MSA", state abbreviation ("NY"), or 5-digit FIPS ("06000"). */
+    geoFips?: string;
+    /** Numeric line code as string, or "ALL". */
+    lineCode?: string;
+    /** "LAST5" (default), "LAST10", "ALL", or comma-separated years. */
+    year?: string;
+}): Promise<BeaStateGdpResult>;
+/** Get personal income data by state from BEA Regional dataset. */
+export declare function getPersonalIncome(opts?: {
+    /** Income table (default: "SAINC1"). See regionalTables in types.ts. */
+    tableName?: string;
+    /** "STATE", "COUNTY", "MSA", state abbreviation, or 5-digit FIPS. */
+    geoFips?: string;
+    /** e.g. "3" for per capita, "1" for total. */
+    lineCode?: string;
+    /** "LAST5" (default), "ALL", or comma-separated years. */
+    year?: string;
+}): Promise<BeaPersonalIncomeResult>;
+/** Get GDP contribution by industry from BEA GDPbyIndustry dataset. */
+export declare function getGdpByIndustry(opts?: {
+    /** Table ID ("1", "5", "25") or "ALL". See gdpIndustryTables in types.ts. */
+    tableId?: string;
+    /** A=annual or Q=quarterly (not all tables support quarterly). */
+    frequency?: string;
+    /** Comma-separated years or "ALL". Defaults to last 3 complete years. */
+    year?: string;
+    /** NAICS code ("11", "21") or "ALL". */
+    industry?: string;
+}): Promise<BeaIndustryGdpResult>;
+/** NIPA Underlying Detail — more granular, lower quality than published aggregates. */
+export declare function getNipaUnderlyingDetail(opts?: {
+    tableName?: string;
+    /** A=annual, Q=quarterly, or M=monthly. */
+    frequency?: string;
+    /** "LAST5", "ALL", "X", or comma-separated years. */
+    year?: string;
+}): Promise<BeaNationalGdpResult>;
+/** Fixed Assets — net stock, depreciation, investment. Annual only. */
+export declare function getFixedAssets(opts?: {
+    tableName?: string;
+    /** "LAST5", "ALL", "X", or comma-separated years. */
+    year?: string;
+}): Promise<BeaNationalGdpResult>;
+/** ITA — U.S. international transactions (balance of payments). */
+export declare function getInternationalTransactions(opts?: {
+    /** BEA indicator code: "BalGds", "BalServ", "ExpGds", etc. Use bea_dataset_info to discover. */
+    indicator?: string;
+    /** Country name ("China"), "AllCountries" (total), or "All" (all breakdowns). */
+    areaOrCountry?: string;
+    /** A=annual, QSA=quarterly seasonally adjusted, QNSA=quarterly not adjusted. */
+    frequency?: string;
+    /** Comma-separated years or "ALL". */
+    year?: string;
+}): Promise<BeaItaResult>;
+/** IIP — U.S. international investment position (assets and liabilities). */
+export declare function getInternationalInvestment(opts?: {
+    /** "FinAssetsExclFinDeriv", "DirInvAssets", etc. Use bea_dataset_info to discover. */
+    typeOfInvestment?: string;
+    /** "Pos" (position), "ChgPosTrans", "ChgPosPrice", "ChgPosXRate". */
+    component?: string;
+    /** A=annual or QNSA=quarterly not seasonally adjusted. */
+    frequency?: string;
+    /** Comma-separated years or "ALL". */
+    year?: string;
+}): Promise<BeaIipResult>;
+/** IntlServTrade — annual U.S. trade in services. */
+export declare function getIntlServTrade(opts?: {
+    typeOfService?: string;
+    tradeDirection?: string;
+    affiliation?: string;
+    areaOrCountry?: string;
+    year?: string;
+}): Promise<BeaIntlServTradeResult>;
+/** MNE — Direct Investment (DI) and Activities of Multinational Enterprises (AMNE).
+ *  For AMNE, ownershipLevel and nonBankAffiliatesOnly are required. */
+export declare function getMultinationalEnterprises(opts: {
+    directionOfInvestment: string;
+    classification: string;
+    year: string;
+    ownershipLevel?: string;
+    nonBankAffiliatesOnly?: string;
+    seriesId?: string;
+    country?: string;
+    industry?: string;
+    state?: string;
+    getFootnotes?: string;
+}): Promise<BeaGenericResult>;
+/** InputOutput — Make, Use, and Requirements tables. */
+export declare function getInputOutput(opts: {
+    tableId: string;
+    year: string;
+}): Promise<BeaGenericResult>;
+/** Underlying GDP by Industry — more detail than getGdpByIndustry. Annual only, from 1997. */
+export declare function getUnderlyingGdpByIndustry(opts?: {
+    /** Numeric table ID as string or "ALL". */
+    tableId?: string;
+    /** A=annual only — no quarterly data available for this dataset. */
+    frequency?: string;
+    /** Comma-separated years or "ALL". Defaults to last 3 complete years. */
+    year?: string;
+    /** NAICS code or "ALL". */
+    industry?: string;
+}): Promise<BeaIndustryGdpResult>;
+/** Clear cached responses. */
+export declare function clearCache(): void;
+//# sourceMappingURL=sdk.d.ts.map

package/dist/apis/bea/sdk.d.ts.map

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