# houston-mcp

A unified [Model Context Protocol](https://modelcontextprotocol.io) server for Houston-area
civic, transit, and flood data. It joins several incompatible public data systems — city open
data, GIS layers, real-time traffic, roadway flood warnings, and transit — behind a small set of
workflow-oriented tools, so an AI assistant can answer questions like *"is my route flooding
right now?"* without the model having to know that TranStar, HCFWS, and the GIS hub each speak a
different query language.

See [`PROPOSAL.md`](./PROPOSAL.md) for the full project rationale, architecture, and phased plan.

**Status: early scaffold.** Tool implementations are stubs. See [Roadmap](#roadmap).

## Why this exists

Existing civic-data MCP servers are generic single-platform wrappers (Socrata-only, CKAN-only).
Houston's public data is spread across five incompatible systems, and none of the flood or
transit data is reachable by any existing server. See the proposal for the full gap analysis.

## Data sources

| Source | System | Docs |
|---|---|---|
| City of Houston Open Data | CKAN | https://data.houstontx.gov |
| COH GIS Data Hub | ArcGIS Hub | https://cohgis-mycity.opendata.arcgis.com |
| Houston TranStar | Custom REST | https://traffic.houstontranstar.org/api/api_doc.aspx |
| Harris County Flood Warning System | Custom | https://www.harriscountyfws.org |
| METRO (Houston transit) | GTFS + GTFS-Realtime | https://api-portal.ridemetro.org |
| Texas Open Data Portal | Socrata | https://data.texas.gov |

## Installation

```bash
# from PyPI (once published)
pip install houston-mcp

# from source
git clone https://github.com/YOUR_USERNAME/houston-mcp.git
cd houston-mcp
pip install -e ".[dev]"
```

## Configuration

Some sources require an API key. Copy `.env.example` to `.env` and fill in what you have —
tools that need a missing key will report that clearly rather than failing silently.

```bash
cp .env.example .env
```

| Variable | Required by | Notes |
|---|---|---|
| `METRO_API_KEY` | `transit_arrivals`, `transit_plan` | Sign up at api-portal.ridemetro.org. See [Attribution](#attribution--terms) below — required by METRO's terms. |
| `TRANSTAR_API_KEY` | `flood_status`, `road_conditions` | Optional for public feeds; contact TranStar for elevated access. |

## Usage with Claude Desktop / Claude Code

Add to your MCP client config:

```json
{
  "mcpServers": {
    "houston": {
      "command": "houston-mcp"
    }
  }
}
```

Or run directly for development:

```bash
python -m houston_mcp.server
```

## Tools

| Tool | Purpose | Sources joined |
|---|---|---|
| `flood_status` | Current flooding risk near a location or along a route | TranStar, HCFWS |
| `road_conditions` | Closures, incidents, and construction on a corridor | TranStar |
| `transit_arrivals` | Real-time arrivals for a stop or address | METRO GTFS-RT |
| `transit_plan` | Route options between two points | METRO GTFS |
| `find_dataset` | Federated dataset discovery | CKAN, ArcGIS, Socrata |
| `query_dataset` | Normalized query against a discovered dataset | CKAN, ArcGIS, Socrata |
| `neighborhood_profile` | Permits, 311, district, flood zone for an address | CKAN, ArcGIS |
| `geocode` | Address → coordinates → local identifiers | Nominatim |

Tool count is capped by design — see `PROPOSAL.md` §3.1 for why this server favors a small
number of workflow tools over one-tool-per-endpoint.

## Safety note on flood data

Flood and roadway-condition data in this server is sourced from public feeds that the
originating agencies (Houston TranStar, Harris County Flood Control District) explicitly
disclaim for accuracy, completeness, and timeliness. **This server is informational only and is
not an authoritative source for emergency decisions.** In an active flood or emergency, consult
official channels (911, local news, National Weather Service, ReadyHarris) directly. Every
flood-related tool response includes a source timestamp and this same disclaimer.

## Attribution & terms

- **METRO**: redistribution requires the legend *"Route and arrival data provided by permission
  of METRO"* to be displayed alongside any METRO-sourced output. This server adds it
  automatically to `transit_arrivals` and `transit_plan` responses — do not strip it in
  downstream use. METRO's license is limited and revocable; review
  https://api-portal.ridemetro.org before relying on it in anything beyond personal/hobby use.
- **TranStar**: usable without prior permission per their published disclaimer; review
  https://traffic.houstontranstar.org/api/api_doc.aspx for current terms.
- **City/County open data**: published for reuse; check per-dataset licenses on the portal for
  anything beyond typical read/analyze use.

## Development

```bash
pip install -e ".[dev]"
pytest tests/                 # integration tests hit live public endpoints
ruff check src/
```

## Roadmap

- [x] Repo scaffold, tool stubs, source client stubs
- [ ] Phase 1: CKAN + ArcGIS clients, `find_dataset`, `query_dataset`, `geocode`
- [ ] Phase 2: TranStar + HCFWS, `flood_status`, `road_conditions`
- [ ] Phase 3: METRO GTFS + GTFS-RT, `transit_arrivals`, `transit_plan`
- [ ] Phase 4: caching, error handling, CI, integration tests
- [ ] Phase 5: publish to PyPI and MCP registries
- [ ] Phase 6: extract city-agnostic core for other metros

Full detail in [`PROPOSAL.md`](./PROPOSAL.md).

## License

MIT — see [`LICENSE`](./LICENSE). Provided as-is with no warranty; see the safety note above
regarding flood and roadway data specifically.