us-macro-mcp 0.1.0__tar.gz

us_macro_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

us_macro_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: us-macro-mcp
+Version: 0.1.0
+Summary: MCP server exposing US macroeconomic indicators - inflation, employment, growth, housing, rates and recession signals - from the Federal Reserve's FRED database.
+Keywords: mcp,model-context-protocol,economics,fred,macro,inflation,llm
+Author: Harish Gupta
+Author-email: Harish Gupta <hgus107@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/hgus107/US-Macro-MCP
+Project-URL: Repository, https://github.com/hgus107/US-Macro-MCP
+Project-URL: Issues, https://github.com/hgus107/US-Macro-MCP/issues
+Description-Content-Type: text/markdown
+
+# US-Macro-MCP
+
+An MCP server that gives AI assistants clean access to US macroeconomic data — 58 indicators covering inflation, employment, growth, housing, consumer behaviour, interest rates, financial stress, markets and federal finances, sourced from the Federal Reserve's FRED database.
+
+It is built so the assistant never has to know a FRED series ID, and never has to do arithmetic. Ask for `cpi` and you get the latest reading, the previous one, the year-ago value, and the percentage changes already calculated.
+
+## What it does
+
+| Tool | What you use it for |
+|---|---|
+| `list_indicators` | See every indicator available, grouped by category |
+| `get_indicator` | The current reading of one indicator, with its changes |
+| `get_history` | A full time series, for trends and charting |
+| `compare_indicators` | Two or more indicators over the same window, normalised for comparison |
+| `release_calendar` | Which economic reports are scheduled over the coming days |
+| `macro_snapshot` | The whole economy — or one category — in a single call |
+| `recession_signals` | The Sahm rule, yield curve, credit spreads, claims and financial conditions, each graded |
+| `search_indicators` | Find an indicator by keyword when you don't know its name |
+
+## Requirements
+
+A free FRED API key. Request one at [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) — it takes about a minute and costs nothing.
+
+## Install
+
+### Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "us-macro": {
+      "command": "uvx",
+      "args": ["us-macro-mcp"],
+      "env": { "FRED_API_KEY": "your_key_here" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add us-macro --env FRED_API_KEY=your_key_here -- uvx us-macro-mcp
+```
+
+### Any other MCP client
+
+Run `uvx us-macro-mcp` with `FRED_API_KEY` set in the environment. The server speaks MCP over stdio.
+
+## How it behaves
+
+**It runs locally.** Nothing is hosted. Your client launches the server as a subprocess on your own machine, using your own API key. No data leaves your computer except the read-only requests to FRED.
+
+**It caches.** A single `macro_snapshot` fetches 19 indicators at once, and conversations tend to ask for the same series repeatedly. Answers are held in memory for a period matched to how often the number can actually change — an hour for daily series like Treasury yields, half a day for monthly series like CPI. The cache is discarded when the process exits. Adjust `CACHE_SECONDS` in `fred.py` if you want different behaviour.
+
+**It never logs your API key.** Requests are logged as endpoint, series and status code only, and any error text is stripped of the key before it is written or returned.
+
+## Known limitations
+
+- **The ISM Manufacturing and Services PMI are not available.** ISM licenses its data commercially and withdrew it from FRED. The same applies to the Conference Board Consumer Confidence Index. There is no free source for either.
+- **Rates are national averages, not per-bank.** The 30-year mortgage rate is Freddie Mac's weekly survey across thousands of lenders — not any particular bank's advertised rate. Per-institution rates are not published free by anyone.
+- **FOMC meeting dates are not included.** FRED publishes data release schedules, not the Federal Reserve's meeting calendar.
+- **Michigan consumer sentiment lags.** As of this writing FRED's `UMCSENT` and `MICH` series are running about two months behind other monthly indicators. The `latest_date` field always tells you what you actually got.
+- **Data is reported for the period it covers.** June CPI is dated `2026-06-01` and publishes in mid-July. Always read `latest_date` rather than assuming the most recent month exists yet.
+
+## Data source and disclaimer
+
+All data comes from [FRED](https://fred.stlouisfed.org/), maintained by the Federal Reserve Bank of St. Louis, which aggregates it from the Bureau of Labor Statistics, the Bureau of Economic Analysis, the Census Bureau, the Federal Reserve Board and others.
+
+The `recession_signals` tool applies well-known statistical thresholds to public data. It is not a forecast, and nothing this server returns is investment advice.
+
+## Annual maintenance checklist
+
+The Federal Reserve publishes its meeting schedule about two years ahead, and Python, the MCP SDK and
+FRED's own catalog all drift over a year. Work through this list every January and cut a new release.
+
+**Data**
+
+- [ ] Refresh the FOMC schedule in `src/us_macro_mcp/fomc.py` from
+      [federalreserve.gov/monetarypolicy/fomccalendars.htm](https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm),
+      and move `VALID_THROUGH` forward. The `next_fomc_meeting` field goes empty once the list runs out.
+- [ ] Re-validate every series ID in the catalog. FRED retires series without warning — the ADP
+      employment series was discontinued this way, returning a valid response with zero observations:
+
+      cd ~/Downloads/Apps/US-Macro-MCP && uv run python -c "
+      import asyncio, logging
+      logging.getLogger('us_macro_mcp').setLevel(logging.WARNING)
+      from us_macro_mcp import catalog, fred
+      async def main():
+          sem = asyncio.Semaphore(8)
+          async def check(i):
+              async with sem:
+                  try:
+                      p = await fred.get_observations(i.series_id, start='2025-01-01', frequency_hint=i.frequency)
+                      return (i.name, 'OK' if p else 'EMPTY', p[-1]['date'] if p else '-')
+                  except Exception as e:
+                      return (i.name, 'FAIL: ' + str(e)[:70], '-')
+          rows = await asyncio.gather(*(check(i) for i in catalog.CATALOG))
+          print('problems:', [r for r in rows if r[1] != 'OK'])
+      asyncio.run(main())
+      "
+
+- [ ] Check whether anything previously unavailable has become free — particularly the ISM PMI and the
+      Conference Board Consumer Confidence Index, both currently absent from FRED.
+- [ ] Check FRED's API terms and rate limit (currently 120 requests per minute per key) for changes.
+
+**Dependencies**
+
+- [ ] Bump the `mcp` SDK and read its changelog for breaking changes. FastMCP is part of the official
+      SDK, so a major version there can change how tools are declared or how the server starts.
+- [ ] Check whether the MCP specification has revised its transports or tool schema.
+- [ ] Bump `httpx`.
+- [ ] Review `requires-python`. Drop versions that have reached end of life, and confirm the current
+      floor still installs cleanly.
+
+**Release**
+
+- [ ] Run the full test sweep: all eight tools, plus the negative and boundary cases.
+- [ ] Bump the version in `pyproject.toml` and in `server.json`. They must match or the registry
+      rejects the publish.
+- [ ] `uv build` and `uv publish` to PyPI.
+- [ ] `mcp-publisher publish` to the official MCP registry.
+- [ ] Tag the release on GitHub.
+
+## License
+
+MIT

us_macro_mcp-0.1.0/README.md

@@ -0,0 +1,129 @@
+# US-Macro-MCP
+
+An MCP server that gives AI assistants clean access to US macroeconomic data — 58 indicators covering inflation, employment, growth, housing, consumer behaviour, interest rates, financial stress, markets and federal finances, sourced from the Federal Reserve's FRED database.
+
+It is built so the assistant never has to know a FRED series ID, and never has to do arithmetic. Ask for `cpi` and you get the latest reading, the previous one, the year-ago value, and the percentage changes already calculated.
+
+## What it does
+
+| Tool | What you use it for |
+|---|---|
+| `list_indicators` | See every indicator available, grouped by category |
+| `get_indicator` | The current reading of one indicator, with its changes |
+| `get_history` | A full time series, for trends and charting |
+| `compare_indicators` | Two or more indicators over the same window, normalised for comparison |
+| `release_calendar` | Which economic reports are scheduled over the coming days |
+| `macro_snapshot` | The whole economy — or one category — in a single call |
+| `recession_signals` | The Sahm rule, yield curve, credit spreads, claims and financial conditions, each graded |
+| `search_indicators` | Find an indicator by keyword when you don't know its name |
+
+## Requirements
+
+A free FRED API key. Request one at [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) — it takes about a minute and costs nothing.
+
+## Install
+
+### Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "us-macro": {
+      "command": "uvx",
+      "args": ["us-macro-mcp"],
+      "env": { "FRED_API_KEY": "your_key_here" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add us-macro --env FRED_API_KEY=your_key_here -- uvx us-macro-mcp
+```
+
+### Any other MCP client
+
+Run `uvx us-macro-mcp` with `FRED_API_KEY` set in the environment. The server speaks MCP over stdio.
+
+## How it behaves
+
+**It runs locally.** Nothing is hosted. Your client launches the server as a subprocess on your own machine, using your own API key. No data leaves your computer except the read-only requests to FRED.
+
+**It caches.** A single `macro_snapshot` fetches 19 indicators at once, and conversations tend to ask for the same series repeatedly. Answers are held in memory for a period matched to how often the number can actually change — an hour for daily series like Treasury yields, half a day for monthly series like CPI. The cache is discarded when the process exits. Adjust `CACHE_SECONDS` in `fred.py` if you want different behaviour.
+
+**It never logs your API key.** Requests are logged as endpoint, series and status code only, and any error text is stripped of the key before it is written or returned.
+
+## Known limitations
+
+- **The ISM Manufacturing and Services PMI are not available.** ISM licenses its data commercially and withdrew it from FRED. The same applies to the Conference Board Consumer Confidence Index. There is no free source for either.
+- **Rates are national averages, not per-bank.** The 30-year mortgage rate is Freddie Mac's weekly survey across thousands of lenders — not any particular bank's advertised rate. Per-institution rates are not published free by anyone.
+- **FOMC meeting dates are not included.** FRED publishes data release schedules, not the Federal Reserve's meeting calendar.
+- **Michigan consumer sentiment lags.** As of this writing FRED's `UMCSENT` and `MICH` series are running about two months behind other monthly indicators. The `latest_date` field always tells you what you actually got.
+- **Data is reported for the period it covers.** June CPI is dated `2026-06-01` and publishes in mid-July. Always read `latest_date` rather than assuming the most recent month exists yet.
+
+## Data source and disclaimer
+
+All data comes from [FRED](https://fred.stlouisfed.org/), maintained by the Federal Reserve Bank of St. Louis, which aggregates it from the Bureau of Labor Statistics, the Bureau of Economic Analysis, the Census Bureau, the Federal Reserve Board and others.
+
+The `recession_signals` tool applies well-known statistical thresholds to public data. It is not a forecast, and nothing this server returns is investment advice.
+
+## Annual maintenance checklist
+
+The Federal Reserve publishes its meeting schedule about two years ahead, and Python, the MCP SDK and
+FRED's own catalog all drift over a year. Work through this list every January and cut a new release.
+
+**Data**
+
+- [ ] Refresh the FOMC schedule in `src/us_macro_mcp/fomc.py` from
+      [federalreserve.gov/monetarypolicy/fomccalendars.htm](https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm),
+      and move `VALID_THROUGH` forward. The `next_fomc_meeting` field goes empty once the list runs out.
+- [ ] Re-validate every series ID in the catalog. FRED retires series without warning — the ADP
+      employment series was discontinued this way, returning a valid response with zero observations:
+
+      cd ~/Downloads/Apps/US-Macro-MCP && uv run python -c "
+      import asyncio, logging
+      logging.getLogger('us_macro_mcp').setLevel(logging.WARNING)
+      from us_macro_mcp import catalog, fred
+      async def main():
+          sem = asyncio.Semaphore(8)
+          async def check(i):
+              async with sem:
+                  try:
+                      p = await fred.get_observations(i.series_id, start='2025-01-01', frequency_hint=i.frequency)
+                      return (i.name, 'OK' if p else 'EMPTY', p[-1]['date'] if p else '-')
+                  except Exception as e:
+                      return (i.name, 'FAIL: ' + str(e)[:70], '-')
+          rows = await asyncio.gather(*(check(i) for i in catalog.CATALOG))
+          print('problems:', [r for r in rows if r[1] != 'OK'])
+      asyncio.run(main())
+      "
+
+- [ ] Check whether anything previously unavailable has become free — particularly the ISM PMI and the
+      Conference Board Consumer Confidence Index, both currently absent from FRED.
+- [ ] Check FRED's API terms and rate limit (currently 120 requests per minute per key) for changes.
+
+**Dependencies**
+
+- [ ] Bump the `mcp` SDK and read its changelog for breaking changes. FastMCP is part of the official
+      SDK, so a major version there can change how tools are declared or how the server starts.
+- [ ] Check whether the MCP specification has revised its transports or tool schema.
+- [ ] Bump `httpx`.
+- [ ] Review `requires-python`. Drop versions that have reached end of life, and confirm the current
+      floor still installs cleanly.
+
+**Release**
+
+- [ ] Run the full test sweep: all eight tools, plus the negative and boundary cases.
+- [ ] Bump the version in `pyproject.toml` and in `server.json`. They must match or the registry
+      rejects the publish.
+- [ ] `uv build` and `uv publish` to PyPI.
+- [ ] `mcp-publisher publish` to the official MCP registry.
+- [ ] Tag the release on GitHub.
+
+## License
+
+MIT

us_macro_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "us-macro-mcp"
+version = "0.1.0"
+description = "MCP server exposing US macroeconomic indicators - inflation, employment, growth, housing, rates and recession signals - from the Federal Reserve's FRED database."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Harish Gupta", email = "hgus107@gmail.com" }
+]
+keywords = ["mcp", "model-context-protocol", "economics", "fred", "macro", "inflation", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "httpx>=0.27",
+    "mcp[cli]>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/hgus107/US-Macro-MCP"
+Repository = "https://github.com/hgus107/US-Macro-MCP"
+Issues = "https://github.com/hgus107/US-Macro-MCP/issues"
+
+[project.scripts]
+us-macro-mcp = "us_macro_mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"

us_macro_mcp-0.1.0/src/us_macro_mcp/__init__.py

@@ -0,0 +1,22 @@
+"""
+US-Macro-MCP - the package entry point.
+
+What this file does, in order:
+1. Exposes the version number to anything that imports this package.
+2. Defines main(), the command the operating system runs when someone types "us-macro-mcp".
+3. main() starts the MCP server, which then waits for an AI client to connect and call its tools.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+# The command line entry point: starts the MCP server and hands control to it.
+def main() -> None:
+    from .server import run
+
+    run()
+
+
+__all__ = ["main", "__version__"]

us_macro_mcp-0.1.0/src/us_macro_mcp/catalog.py

@@ -0,0 +1,254 @@
+"""
+The indicator catalog for US-Macro-MCP.
+
+What this file does, in order:
+1. Defines one Indicator record per economic statistic we support - its friendly
+   name, its FRED series ID, which category it belongs to, and how often it updates.
+2. Lists all 58 indicators, grouped by category, in the CATALOG tuple.
+3. Builds lookup dictionaries so the rest of the program can find an indicator
+   by its friendly name (for example "cpi") or by its FRED series ID.
+4. Provides small helper functions to search the catalog and to list the categories.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# One economic indicator: the friendly name users ask for, plus everything we need to fetch and label it.
+@dataclass(frozen=True)
+class Indicator:
+    name: str           # friendly name used in tool arguments, e.g. "core_cpi"
+    series_id: str      # the FRED series ID we actually request, e.g. "CPILFESL"
+    title: str          # human-readable title shown in results
+    category: str       # one of the CATEGORIES below
+    units: str          # what the numbers mean, e.g. "Percent" or "Index 1982-84=100"
+    frequency: str      # how often FRED updates it: Daily, Weekly, Monthly, Quarterly
+    major: bool = False # True for headline indicators included in snapshots and the calendar
+    notes: str = ""     # optional one-line explanation of how to read the number
+
+
+CATEGORIES = (
+    "inflation",
+    "employment",
+    "growth",
+    "housing",
+    "consumer",
+    "rates",
+    "stress",
+    "markets",
+    "fiscal",
+)
+
+
+CATALOG: tuple[Indicator, ...] = (
+    # ---------------------------------------------------------------- inflation
+    Indicator("cpi", "CPIAUCSL", "Consumer Price Index (All Items)", "inflation",
+              "Index 1982-84=100", "Monthly", major=True,
+              notes="Headline inflation; read the year-over-year percent change."),
+    Indicator("core_cpi", "CPILFESL", "Core CPI (Excluding Food and Energy)", "inflation",
+              "Index 1982-84=100", "Monthly", major=True,
+              notes="Strips out volatile food and energy prices."),
+    Indicator("pce", "PCEPI", "PCE Price Index", "inflation",
+              "Index 2017=100", "Monthly",
+              notes="The broader price measure the Federal Reserve prefers."),
+    Indicator("core_pce", "PCEPILFE", "Core PCE Price Index", "inflation",
+              "Index 2017=100", "Monthly", major=True,
+              notes="The Federal Reserve's official 2 percent inflation target measure."),
+    Indicator("ppi", "PPIFIS", "Producer Price Index (Final Demand)", "inflation",
+              "Index 2009=100", "Monthly", major=True,
+              notes="Prices producers receive; often leads consumer prices."),
+    Indicator("breakeven_5y", "T5YIE", "5-Year Breakeven Inflation Rate", "inflation",
+              "Percent", "Daily",
+              notes="What the bond market expects inflation to average over 5 years."),
+    Indicator("breakeven_10y", "T10YIE", "10-Year Breakeven Inflation Rate", "inflation",
+              "Percent", "Daily"),
+
+    # --------------------------------------------------------------- employment
+    Indicator("unemployment_rate", "UNRATE", "Unemployment Rate", "employment",
+              "Percent", "Monthly", major=True),
+    Indicator("nonfarm_payrolls", "PAYEMS", "Total Nonfarm Payrolls", "employment",
+              "Thousands of Persons", "Monthly", major=True,
+              notes="Read the month-over-month change - that is the 'jobs number'."),
+    Indicator("private_payrolls", "USPRIV", "All Employees, Total Private", "employment",
+              "Thousands of Persons", "Monthly",
+              notes="Jobs at private employers only - excludes government hiring."),
+    Indicator("jobless_claims", "ICSA", "Initial Jobless Claims", "employment",
+              "Number", "Weekly", major=True,
+              notes="Weekly new unemployment filings; the fastest labor market signal."),
+    Indicator("continuing_claims", "CCSA", "Continuing Jobless Claims", "employment",
+              "Number", "Weekly",
+              notes="People still collecting benefits; shows how hard it is to get rehired."),
+    Indicator("job_openings", "JTSJOL", "Job Openings (JOLTS)", "employment",
+              "Thousands", "Monthly", major=True),
+    Indicator("labor_participation", "CIVPART", "Labor Force Participation Rate", "employment",
+              "Percent", "Monthly"),
+    Indicator("avg_hourly_earnings", "CES0500000003", "Average Hourly Earnings", "employment",
+              "Dollars per Hour", "Monthly",
+              notes="Wage growth; compare its year-over-year change against CPI."),
+
+    # ------------------------------------------------------------------- growth
+    Indicator("gdp", "GDPC1", "Real Gross Domestic Product", "growth",
+              "Billions of Chained 2017 Dollars", "Quarterly", major=True,
+              notes="Inflation-adjusted output; the headline growth number."),
+    Indicator("gdp_nominal", "GDP", "Nominal Gross Domestic Product", "growth",
+              "Billions of Dollars", "Quarterly"),
+    Indicator("industrial_production", "INDPRO", "Industrial Production Index", "growth",
+              "Index 2017=100", "Monthly"),
+    Indicator("capacity_utilization", "TCU", "Capacity Utilization", "growth",
+              "Percent of Capacity", "Monthly"),
+    Indicator("durable_goods", "DGORDER", "Durable Goods New Orders", "growth",
+              "Millions of Dollars", "Monthly",
+              notes="Business orders for long-lasting goods; a capital spending gauge."),
+    Indicator("productivity", "OPHNFB", "Nonfarm Business Labor Productivity", "growth",
+              "Index 2017=100", "Quarterly"),
+    Indicator("philly_fed", "GACDFSA066MSFRBPHI", "Philadelphia Fed Manufacturing Survey", "growth",
+              "Diffusion Index", "Monthly",
+              notes="Above zero means more factories reporting growth than decline."),
+    Indicator("empire_state", "GACDISA066MSFRBNY", "Empire State Manufacturing Survey", "growth",
+              "Diffusion Index", "Monthly",
+              notes="New York Fed factory survey; the earliest monthly read on manufacturing."),
+    Indicator("national_activity", "CFNAI", "Chicago Fed National Activity Index", "growth",
+              "Index", "Monthly",
+              notes="85 indicators combined; zero is average growth, negative is below trend."),
+
+    # ------------------------------------------------------------------ housing
+    Indicator("housing_starts", "HOUST", "Housing Starts", "housing",
+              "Thousands of Units (Annual Rate)", "Monthly", major=True),
+    Indicator("building_permits", "PERMIT", "Building Permits", "housing",
+              "Thousands of Units (Annual Rate)", "Monthly",
+              notes="Leads housing starts by a month or two."),
+    Indicator("new_home_sales", "HSN1F", "New One-Family Home Sales", "housing",
+              "Thousands of Units (Annual Rate)", "Monthly"),
+    Indicator("existing_home_sales", "EXHOSLUSM495S", "Existing Home Sales", "housing",
+              "Number of Units (Annual Rate)", "Monthly"),
+    Indicator("home_prices", "CSUSHPINSA", "Case-Shiller National Home Price Index", "housing",
+              "Index Jan 2000=100", "Monthly",
+              notes="Reported with a two-month lag."),
+    Indicator("mortgage_30y", "MORTGAGE30US", "30-Year Fixed Mortgage Rate", "housing",
+              "Percent", "Weekly", major=True,
+              notes="Freddie Mac national average, not any single lender's rate."),
+    Indicator("mortgage_15y", "MORTGAGE15US", "15-Year Fixed Mortgage Rate", "housing",
+              "Percent", "Weekly"),
+
+    # ----------------------------------------------------------------- consumer
+    Indicator("retail_sales", "RSAFS", "Retail and Food Services Sales", "consumer",
+              "Millions of Dollars", "Monthly", major=True),
+    Indicator("consumer_sentiment", "UMCSENT", "University of Michigan Consumer Sentiment", "consumer",
+              "Index 1966Q1=100", "Monthly", major=True),
+    Indicator("inflation_expectations", "MICH", "Michigan 1-Year Inflation Expectations", "consumer",
+              "Percent", "Monthly",
+              notes="What households think inflation will be over the next year."),
+    Indicator("personal_income", "PI", "Personal Income", "consumer",
+              "Billions of Dollars (Annual Rate)", "Monthly"),
+    Indicator("personal_spending", "PCE", "Personal Consumption Expenditures", "consumer",
+              "Billions of Dollars (Annual Rate)", "Monthly"),
+    Indicator("savings_rate", "PSAVERT", "Personal Saving Rate", "consumer",
+              "Percent of Disposable Income", "Monthly"),
+    Indicator("consumer_credit", "TOTALSL", "Total Consumer Credit Outstanding", "consumer",
+              "Billions of Dollars", "Monthly",
+              notes="How much household borrowing is building up."),
+
+    # -------------------------------------------------------------------- rates
+    Indicator("fed_funds", "DFF", "Effective Federal Funds Rate", "rates",
+              "Percent", "Daily", major=True,
+              notes="The overnight rate the Federal Reserve steers with policy decisions."),
+    Indicator("sofr", "SOFR", "Secured Overnight Financing Rate", "rates",
+              "Percent", "Daily"),
+    Indicator("treasury_3m", "DGS3MO", "3-Month Treasury Yield", "rates",
+              "Percent", "Daily"),
+    Indicator("treasury_2y", "DGS2", "2-Year Treasury Yield", "rates",
+              "Percent", "Daily"),
+    Indicator("treasury_10y", "DGS10", "10-Year Treasury Yield", "rates",
+              "Percent", "Daily", major=True),
+    Indicator("treasury_30y", "DGS30", "30-Year Treasury Yield", "rates",
+              "Percent", "Daily"),
+    Indicator("yield_curve", "T10Y2Y", "10-Year Minus 2-Year Treasury Spread", "rates",
+              "Percent", "Daily", major=True,
+              notes="Below zero is an inverted curve, historically a recession warning."),
+    Indicator("fed_balance_sheet", "WALCL", "Federal Reserve Total Assets", "rates",
+              "Millions of Dollars", "Weekly",
+              notes="Shrinking means the Federal Reserve is draining liquidity."),
+
+    # ------------------------------------------------------------------- stress
+    Indicator("high_yield_spread", "BAMLH0A0HYM2", "High Yield Bond Spread", "stress",
+              "Percent", "Daily", major=True,
+              notes="Extra yield demanded on risky corporate debt; widens when credit is stressed."),
+    Indicator("financial_conditions", "NFCI", "Chicago Fed National Financial Conditions Index", "stress",
+              "Index", "Weekly",
+              notes="Above zero means conditions are tighter than average."),
+    Indicator("sahm_rule", "SAHMREALTIME", "Sahm Rule Recession Indicator", "stress",
+              "Percentage Points", "Monthly", major=True,
+              notes="At or above 0.50 has historically meant a recession has begun."),
+    Indicator("lending_standards", "DRTSCILM", "Banks Tightening Business Lending Standards", "stress",
+              "Net Percent of Banks", "Quarterly",
+              notes="From the Fed's Senior Loan Officer Survey; rising means credit is getting harder to get."),
+
+    # ------------------------------------------------------------------ markets
+    Indicator("sp500", "SP500", "S&P 500 Index", "markets",
+              "Index", "Daily", major=True),
+    Indicator("vix", "VIXCLS", "CBOE Volatility Index (VIX)", "markets",
+              "Index", "Daily",
+              notes="Expected stock market volatility; spikes signal fear."),
+    Indicator("dollar_index", "DTWEXBGS", "Trade Weighted US Dollar Index", "markets",
+              "Index Jan 2006=100", "Daily"),
+    Indicator("wti_crude", "DCOILWTICO", "WTI Crude Oil Price", "markets",
+              "Dollars per Barrel", "Daily"),
+    Indicator("gas_price", "GASREGW", "US Regular Gasoline Price", "markets",
+              "Dollars per Gallon", "Weekly"),
+
+    # ------------------------------------------------------------------- fiscal
+    Indicator("federal_debt", "GFDEBTN", "Total Federal Public Debt", "fiscal",
+              "Millions of Dollars", "Quarterly"),
+    Indicator("federal_deficit", "MTSDS133FMS", "Federal Surplus or Deficit", "fiscal",
+              "Millions of Dollars", "Monthly",
+              notes="Negative values are deficits."),
+    Indicator("debt_to_gdp", "GFDEGDQ188S", "Federal Debt as Percent of GDP", "fiscal",
+              "Percent of GDP", "Quarterly"),
+)
+
+
+# Fast lookups built once at import: friendly name -> Indicator, and FRED series ID -> Indicator.
+BY_NAME: dict[str, Indicator] = {item.name: item for item in CATALOG}
+BY_SERIES_ID: dict[str, Indicator] = {item.series_id: item for item in CATALOG}
+
+
+# Finds one indicator by friendly name, or by FRED series ID if the caller passed that instead.
+def find(name: str) -> Indicator | None:
+    key = name.strip().lower().replace("-", "_").replace(" ", "_")
+    if key in BY_NAME:
+        return BY_NAME[key]
+    return BY_SERIES_ID.get(name.strip().upper())
+
+
+# Returns every indicator in one category, or the whole catalog when no category is given.
+def in_category(category: str | None) -> tuple[Indicator, ...]:
+    if not category or category.lower() == "all":
+        return CATALOG
+    wanted = category.strip().lower()
+    return tuple(item for item in CATALOG if item.category == wanted)
+
+
+# Scores each indicator against a free-text query and returns the best matches first.
+def search(query: str, limit: int = 10) -> list[Indicator]:
+    words = [w for w in query.strip().lower().split() if w]
+    if not words:
+        return []
+
+    scored: list[tuple[int, Indicator]] = []
+    for item in CATALOG:
+        haystack = " ".join(
+            (item.name, item.title, item.category, item.notes, item.series_id)
+        ).lower()
+        score = 0
+        for word in words:
+            if word in item.name.lower():
+                score += 3          # a hit on the friendly name is the strongest signal
+            elif word in item.title.lower():
+                score += 2          # a hit in the official title is next best
+            elif word in haystack:
+                score += 1          # a hit anywhere else still counts a little
+        if score:
+            scored.append((score, item))
+
+    scored.sort(key=lambda pair: (-pair[0], pair[1].name))
+    return [item for _, item in scored[:limit]]