# census-mcp

Remote MCP server exposing **US Census (ACS 5-year)** and **FEMA flood** data.
Works as a connector in both **Claude** and **ChatGPT**. Separate service from
`dmap-ai-mcp` (own folder, own port 8020, own repo) — the drought server is not
touched.

## Tools

| Tool | What it does |
|---|---|
| `resolve_location(lat, lon)` | Point → state / county / tract / block group + GEOIDs |
| `search_variables(keyword)` | Search ~28,000 ACS variables ("Korean", "median income"...) |
| `get_cell_data(variables, fips...)` | Values for chosen variables in one cell |
| `find_cells(variable, area, min_value)` | All cells in a state/USA containing an item, auto geography fallback |
| `get_flood_zone(lat, lon)` | FEMA NFHL flood zone for a point |
| `area_profile(lat, lon)` | One-call profile: population, income, rent, age + flood zone |
| `search(query)` / `fetch(id)` | ChatGPT-required pair (standard connectors & deep research) wrapping the cell finder |

## Run locally

```bash
cd census-mcp
python -m venv venv && venv\Scripts\activate    # Windows
pip install -r requirements.txt
set CENSUS_API_KEY=your_key                     # free: https://api.census.gov/data/key_signup.html
set MCP_ACCESS_KEY=some-long-random-secret
uvicorn server:app --port 8020
```

Smoke test (should return the tool list):

```bash
curl -s -X POST "http://127.0.0.1:8020/census-mcp/some-long-random-secret/" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## GitHub

```bash
cd census-mcp
git init
git add .
git commit -m "census-mcp: initial version"
# create an empty repo named census-mcp at github.com/new (private is fine), then:
git remote add origin https://github.com/sohrab4748/census-mcp.git
git push -u origin main
```

Never commit real keys — they live only in the systemd unit / environment.

## Deploy on the DigitalOcean droplet

```bash
ssh your-droplet
sudo git clone https://github.com/sohrab4748/census-mcp.git /opt/census-mcp
cd /opt/census-mcp
sudo python3 -m venv venv && sudo venv/bin/pip install -r requirements.txt

sudo cp deploy/census-mcp.service /etc/systemd/system/
sudo nano /etc/systemd/system/census-mcp.service   # put real CENSUS_API_KEY + MCP_ACCESS_KEY
sudo systemctl daemon-reload && sudo systemctl enable --now census-mcp
sudo systemctl status census-mcp                   # should be active (running)
```

Then add the contents of `deploy/nginx-snippet.conf` inside the existing
`server {}` block for droughtanalysis.com and run
`sudo nginx -t && sudo systemctl reload nginx`.

Your connector URL becomes:

```
https://droughtanalysis.com/census-mcp/<MCP_ACCESS_KEY>/
```

The secret in the URL is the access control (chosen for launch); anyone
without it gets 404. Rotate it by changing the env var and restarting.

## Connect it

**Claude** (claude.ai or desktop): Settings → Connectors → *Add custom
connector* → paste the URL above.

**ChatGPT**: Settings → Apps & Connectors → enable *Developer mode* →
*Create* → paste the same URL (no auth). Then enable it in a conversation or
attach it to a custom GPT.

## Notes / roadmap

- ACS vintage is pinned via `ACS_YEAR` (default 2023); bump when 2024 5-year drops.
- `find_cells` with `area="USA"` starts at county level by design — block-group
  scans of all 50 states are too slow for a single tool call.
- Census and FEMA requests share one connection-pooled HTTP client. Transient
  transport failures, HTTP 429 responses, and 5xx responses are retried up to
  three times with exponential backoff.
- Coordinates, ACS variable IDs, and hierarchical FIPS components are validated
  before an upstream request. ACS calls accept at most 45 variables.
- Upstream payloads are bounded (8 MiB normally and 32 MiB for the cached ACS
  variable catalog). The catalog is downloaded once per process, including when
  multiple first-use requests arrive concurrently.
- Install `requirements-dev.txt` and run `python -m pytest -q` for the fully
  mocked test suite; tests never call the live Census or FEMA APIs.
- Later: real OAuth, usage metering, per-user favorites ("favorite reports"),
  more datasets (Decennial, County Business Patterns, TIGER boundaries).
"# census-mcp"