Metadata-Version: 2.4
Name: mytown-mcp
Version: 0.1.1
Summary: MCP server for MyTown — US & Canadian local-government meetings, decisions, and place context, grounded in official sources.
Project-URL: Homepage, https://mytown.theboringparts.com
Project-URL: Dataset, https://huggingface.co/datasets/jazzypajamas/mytown-local-gov-meetings
Author: MyTown / The Boring Parts
License: MIT
Keywords: civic-tech,government,local-government,mcp,meetings,open-data
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# MyTown MCP server

<!-- mcp-name: io.github.mrjakob07/mytown-mcp -->

An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant grounded,
**source-linked** access to **US & Canadian local-government meetings** — what your city
council, county board, or school board has coming up and recently decided, in plain
English, plus place context (demographics, home-value trends, federal awards, permits,
campaign finance, EPA/nonprofit ties). Every record links back to the official primary
source.

Data comes from [MyTown](https://mytown.theboringparts.com)'s public, keyless HTTP API, so
this server needs **no API key and no local database** — it works out of the box for
anyone. Coverage: ~2,400 municipalities (US + Canada), refreshed daily.

## Tools

**Per-city** (great for "what's happening in *my* town"):

| tool | what it does |
|---|---|
| `list_cities(query, state, country, limit)` | find covered cities; resolve a place name → the `slug` the other tools need |
| `get_city_meetings(slug)` | upcoming + recent meetings: date, body, plain-English headline/summary, agenda/minutes/source links |
| `get_city_context(slug)` | everything for a city: meetings **plus** demographics, home-value trend, federal awards, permits, campaign-finance summary, and per-decision EPA/nonprofit context |

**Whole-dataset** (cross-city — every table, no download; backed by HuggingFace's hosted dataset-viewer API):

| tool | what it does |
|---|---|
| `dataset_tables()` | the 17 tables, their columns, and join keys — so you know what to search/filter |
| `search_dataset(query, table, limit)` | full-text search across **all cities** in a table (e.g. every `decisions` row mentioning "rent control") |
| `filter_dataset(table, where, order_by, descending, limit)` | structured SQL-style filter (e.g. `federal_awards` where `"amount" > 5000000`, sorted) |
| `dataset_info()` | coverage counts + pointers to bulk Parquet / full SQLite for heavy analysis |

Typical flows: `list_cities("palo alto")` → `get_city_context(slug)` for one place; or
`dataset_tables()` → `search_dataset("police budget", "decisions")` to sweep the whole country.

## Install & configure

### Claude Desktop
Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "mytown": {
      "command": "uvx",
      "args": ["mytown-mcp"]
    }
  }
}
```

Or run from a local checkout (no publish needed):

```json
{
  "mcpServers": {
    "mytown": {
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": ["-m", "mytown_mcp.server"]
    }
  }
}
```

### Claude Code
```bash
# from a local checkout:
claude mcp add mytown -- /absolute/path/to/mcp-server/.venv/bin/python -m mytown_mcp.server
# or, once published:
claude mcp add mytown -- uvx mytown-mcp
```

### From source
```bash
python -m venv .venv && .venv/bin/pip install mcp httpx
.venv/bin/python -m mytown_mcp.server   # speaks MCP over stdio
```

## Example questions it can answer
- "What's the Palo Alto city council deciding this month?"
- "Show recent school-board meetings for the Palo Alto Unified School District."
- "For Lake Forest, CA — pull demographics, home-value trend, and any federal awards."
- "Across the whole country, which towns passed rent-control decisions this year?" (search_dataset)
- "Show the largest federal awards in the dataset, over $1B." (filter_dataset)
- "Find meetings tied to EPA facilities with an identified violation." (filter_dataset on `decision_echo`)

## Notes
- Meeting/decision summaries are **AI-generated from official documents** — always verify
  against the linked primary source before relying on a detail.
- License: **CC BY 4.0** (attribution: mytown.theboringparts.com).
- For research spanning many cities (training, full-text search, bulk stats), use the
  [open dataset](https://huggingface.co/datasets/jazzypajamas/mytown-local-gov-meetings)
  rather than looping these tools.
