# OpenUSPublicDataMCP

Federal-first, no-key-first MCP access to high-value US public data sources.

This is the US counterpart to `OpenUKPublicDataMCP`, but it deliberately separates federal coverage from the fragmented state and local ecosystem. Reusable Socrata, ArcGIS REST and CKAN adapters provide platform coverage without pretending that jurisdictions share one schema.

## Current bootstrap status

- FastMCP server with stdio transport
- source registry with provenance metadata
- `health_check`
- `list_public_data_sources`
- `find_us_data_sources` — filter the registry by jurisdiction or platform
- `resolve_us_geography` — resolve state names/abbreviations/city-state strings to state FIPS
- `search_data_gov` against the official Data.gov CKAN API (endpoint under re-discovery after live 404)
- `get_census_state_population` against the official Census ACS API (optional key)
- `list_federal_agencies` against the official USAspending API (no key)
- `search_federal_register` against the official Federal Register API (no key)
- `search_usaspending_awards` against the official USAspending awards API (no key)
- `search_congress_bills` against the official Congress.gov API (optional key)
- `search_socrata_catalog` and `query_socrata_dataset`
- `query_arcgis_feature_service`
- `search_ckan_catalog`
- `list_curated_state_portals` — California, New York, Texas, Washington and Florida
- `search_state_data` — dispatch to the selected state's curated portal
- mocked tests and project verification spine

## Current status

Q2 2026 validation is complete: 16 MCP tools, five curated state portal packs, stdio and Streamable HTTP transport, DynamicMCPProxy catalogue metadata, and a React/Leaflet US discovery explorer. See `docs/tests/Q2-executive-report.md` for the evidence-based executive snapshot.

## Web discovery explorer

```bash
./scripts/run-web.sh
# http://127.0.0.1:8787
```

The explorer maps all 50 states plus DC using approximate label centroids, distinguishes the five curated official state portals, searches the registered federal/state-local source catalogue, and preserves jurisdiction, auth, platform, licence and coverage status. It is a discovery surface—not a claim of complete state/local coverage or analytical boundary data. Development instructions are in `web/README.md`.

## Quick start

```bash
cd OpenUSPublicDataMCP
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest
fastmcp inspect src/openuspublicdata_mcp/server.py:mcp
fastmcp list src/openuspublicdata_mcp/server.py --json
fastmcp call src/openuspublicdata_mcp/server.py search_data_gov query='climate' limit=3 --json
```

## Direction

1. Curated state packs and local discovery.
2. Federal breadth: BLS, BEA, NOAA, EPA, FDA, CDC and USDA.
3. County FIPS, congressional districts and richer Census geography.
4. HTTP deployment, DynamicMCPProxy and Hermes registration.

See `docs/plans/2026-07-11-openuspublicdata-mcp-bootstrap.md` and `research/LINKS.md`.

## HTTP transport

```bash
OPENUS_PORT=8787 .venv/bin/openuspublicdata-http
curl http://127.0.0.1:8787/health
# MCP endpoint: http://127.0.0.1:8787/mcp
```

The DynamicMCPProxy catalogue entry is in `integrations/dynamic-mcp-proxy-user-catalogue-entry.json`. Hermes can use the stdio server directly:

```bash
hermes config set mcp_servers.openuspublicdata.command "/absolute/path/to/OpenUSPublicDataMCP/.venv/bin/python"
hermes config set mcp_servers.openuspublicdata.args '["-m", "openuspublicdata_mcp.server"]'
```