ConsumerSim Proxy

ConsumerSim provides consumer confidence forecasts for three markets:

• US
• EU27
• JP

Users can access the forecasts in two ways:

• View the public forecast website hosted from this repository.
• Connect to the MCP server and ask for forecasts by region, month, and optional week.

This repository is an interface package only. It does not publish the private forecasting pipeline, model prompts, data refresh logic, source API keys, or private datasets.

What You Can Ask For

Use forecast_lookup when you need a forecast value.

Monthly forecast:

{
  "region": "US",
  "month": "2026-07"
}

Weekly forecast:

{
  "region": "EU27",
  "month": "2026-07",
  "week": 1
}

Supported inputs:

• region: US, EU27, or JP
• month: target month in YYYY-MM format
• week: optional week number within that month, such as 1, 2, 3, or 4

Use forecast_times to see which forecast periods are available.

{
  "region": "JP"
}

Typical Response

forecast_lookup returns a forecast snapshot like this:

{
  "region": "EU27",
  "cadence": "weekly",
  "requested_month": "2026-06",
  "requested_week": "Jun W4",
  "target_month": "2026-07",
  "target_period": "Jul-26",
  "week_label": "Jun W4",
  "as_of": "2026-07-04",
  "forecast": -13.32,
  "interval_low": -14.71,
  "interval_high": -12.39,
  "signal": "Softening signal",
  "interpretation": "Weekly nowcast through 2026-06-27 from the ConsumerSim pipeline."
}

The exact fields may vary by backend version, but the response is designed to include the requested region and time, the forecast value, a confidence band, and a short interpretation.

Run As An MCP Server

Install the package:

python -m pip install -e .

Configure the private backend endpoint:

$env:CONSUMERSIM_API_BASE_URL = "https://your-consumersim-backend.example.com"
$env:CONSUMERSIM_API_KEY = "<your access token>"

Start the MCP server:

consumersim-mcp

The MCP server exposes:

• forecast_lookup
• forecast_times

It forwards requests to the configured ConsumerSim backend and returns the backend result to the MCP client.

Run The Website Locally

The website is a static forecast dashboard under site/.

For a local preview backed by the private API:

python -m pip install -e .
$env:CONSUMERSIM_API_BASE_URL = "https://your-consumersim-backend.example.com"
$env:CONSUMERSIM_API_KEY = "<your access token>"
consumersim-web

Open:

http://127.0.0.1:4173

The local web bridge serves the static site and proxies /api/site-data to the private backend. This keeps backend credentials out of browser JavaScript.

Public Website Deployment

The recommended public deployment is GitHub Pages.

The included workflow:

.github/workflows/refresh-site.yml

does the following:

1. Optionally writes site/site-config.js from CONSUMERSIM_SITE_DATA_URL.
2. Runs the public interface tests.
3. Deploys the site/ directory to GitHub Pages.

The repository does not commit site/data/consumersim_site_data.csv. The website reads site data at runtime from window.CONSUMERSIM_SITE_DATA_URL or from /api/site-data when served by the local web bridge.

The browser checks the runtime site-data endpoint every 60 seconds and refreshes the rendered values when the CSV response changes. Set window.CONSUMERSIM_SITE_DATA_REFRESH_MS in site/site-config.js to override that interval, or set it to 0 to disable polling.

Repository setup:

• Set Pages source to GitHub Actions.
• Add CONSUMERSIM_SITE_DATA_URL as a repository variable when deploying to GitHub Pages.

Do not put source data API keys or model API keys in GitHub. Those belong only on the private backend server.

Backend Settings

Required:

• CONSUMERSIM_API_BASE_URL

Usually required:

• CONSUMERSIM_API_KEY

Optional:

• CONSUMERSIM_FORECAST_PATH, default /forecast
• CONSUMERSIM_TIMES_PATH, default /forecast/times
• CONSUMERSIM_SITE_DATA_PATH, default /site-data
• CONSUMERSIM_API_KEY_HEADER, default Authorization
• CONSUMERSIM_API_KEY_SCHEME, default Bearer
• CONSUMERSIM_TIMEOUT_SECONDS, default 30

Backend Contract

The proxy calls these backend routes:

• POST {CONSUMERSIM_API_BASE_URL}/forecast
• GET {CONSUMERSIM_API_BASE_URL}/forecast/times
• GET {CONSUMERSIM_API_BASE_URL}/site-data

Expected POST /forecast request:

{
  "region": "EU27",
  "month": "2026-06",
  "week": 4
}

Expected GET /site-data response:

as_of,record_type,region,...
2026-07-04,monthly_prediction,us,...

Repository Boundary

This public repository should contain only:

• MCP proxy code
• public website assets
• GitHub Pages deployment workflow
• tests for the public interface
• examples and documentation for users

Do not commit:

• generated site CSV files
• private forecasting pipeline code
• model prompts or internal simulation logic
• private data refresh scripts
• source API keys
• LLM API keys
• private datasets

The private backend can update forecasts without exposing the internal ConsumerSim implementation.