Metadata-Version: 2.4
Name: ontario-data-mcp
Version: 0.2.0
Summary: MCP server for searching, downloading, and analyzing datasets from Ontario, Toronto, and Ottawa open data portals
Project-URL: Homepage, https://sprine.github.io/ontario-data-mcp/
Project-URL: Repository, https://github.com/sprine/ontario-data-mcp
Project-URL: Documentation, https://github.com/sprine/ontario-data-mcp#readme
Project-URL: Changelog, https://github.com/sprine/ontario-data-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/sprine/ontario-data-mcp/issues
Author: A. Mathur
License-Expression: MIT
License-File: LICENSE
Keywords: ckan,duckdb,mcp,ontario,open-data,ottawa,toronto
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.1.0
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: geopandas>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: shapely>=2.0.0
Description-Content-Type: text/markdown

<!-- mcp-name: ontario-data-mcp -->

# ontario-data-mcp

> [!IMPORTANT]  
> **Beta:** This project is under active development. The data structure and tool interfaces may change.
> LLM-generated analysis may contain errors. Always verify critical findings against the returned source data.

This is an [MCP server](https://modelcontextprotocol.io) for discovering, downloading, querying, and analyzing datasets from Ontario's Open Data portals. It allows asking questions of the data in English (or Spanish, Chinese, French, etc).

It currently supports the Ontario, Toronto, and Ottawa portals, and utilizes a shared [DuckDB](https://duckdb.org/) cache for fast SQL queries, statistical analysis, and geospatial operations.

## Contributing

Contributions welcome! To get started, see **Installation** below.

Found a bug? Have an idea? Discovered something interesting?
Open an issue here: https://github.com/sprine/ontario-data-mcp/issues

## Features
* `find` - search across supported Ontario open data portals
* `download` - retrieve and cache datasets
* `query` - run SQL, statistical, and geospatial analysis via DuckDB
* `validate` — verify that data claims are supported by query results
* A shared DuckDB cache for high-performance analytics

```
Portal APIs find → Dataset download → DuckDB cache → MCP tools (find, download, query)
```

## Installation

### With Claude Code

```bash
claude mcp add ontario-data -- uvx ontario-data-mcp
```

To auto-approve all tool calls (no confirmation prompts), add to your Claude Code settings:

```json
{
  "permissions": {
    "allow": ["mcp:ontario-data:*"]
  }
}
```

Tools are annotated as read-only or destructive per the MCP spec. Download tools populate the local cache but are read-only (no remote mutations). Destructive tools (`cache_manage`, `refresh_cache`) only modify local cached data.

<details>
  <summary>With VS Code</summary>

Add to `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "ontario-data": {
      "command": "uvx",
      "args": ["ontario-data-mcp"]
    }
  }
}
```
</details>

<details>
  <summary>From Source</summary>

```bash
git clone https://github.com/sprine/ontario-data-mcp
cd ontario-data-mcp
uv sync
uv run ontario-data-mcp
```

To connect from source to Claude Code:

> **Note:** MCP subprocesses don't inherit your shell's PATH, so you must use the absolute path to `uv` (find it with `which uv`).

```bash
claude mcp add ontario-data -- /absolute/path/to/uv run --directory /path/to/ontario-data-mcp ontario-data-mcp
```
</details>

## Supported Portals

All searches fan out to every portal by default — no need to select a portal. Dataset and resource IDs are prefixed with their portal (e.g. `toronto:abc123`).

| Portal | Platform | Datasets |
|--------|----------|----------|
| `ontario` | CKAN | ~5,700 |
| `toronto` | CKAN | ~533 |
| `ottawa` | ArcGIS Hub | ~665 |

## List of tools available to the AI agent

<details>
<summary><b>Discovery</b> (5 tools)</summary>

| Tool | Description |
|------|-------------|
| `search_datasets` | Search for datasets across all portals (or narrow with `portal=`) |
| `list_portals` | List all available portals with platform type |
| `list_organizations` | List government ministries with dataset counts |
| `list_topics` | List all tags/topics in the catalogue |
| `find_related_datasets` | Find datasets related by tags and organization |

</details>

<details>
<summary><b>Metadata</b> (4 tools)</summary>

| Tool | Description |
|------|-------------|
| `get_dataset_info` | Get full metadata for a dataset (use prefixed ID like `toronto:abc123`) |
| `list_resources` | List all files in a dataset with formats and sizes |
| `get_resource_schema` | Get column schema and sample values for a datastore resource |
| `compare_datasets` | Compare metadata side-by-side for multiple datasets (cross-portal) |

</details>

<details>
<summary><b>Retrieval & Caching</b> (4 tools)</summary>

| Tool | Description |
|------|-------------|
| `download_resource` | Download a resource and cache it in DuckDB (use prefixed ID like `toronto:abc123`) |
| `cache_info` | Cache statistics + list all cached datasets with staleness |
| `cache_manage` | Remove a single cached resource or clear the entire cache |
| `refresh_cache` | Re-download cached resources with latest data |

</details>

<details>
<summary><b>Querying</b> (4 tools)</summary>

| Tool | Description |
|------|-------------|
| `query_resource` | Query a resource via CKAN Datastore API (remote) |
| `sql_query` | Run SQL against the CKAN Datastore (remote) |
| `query_cached` | Run SQL against locally cached data in DuckDB |
| `preview_data` | Quick preview of first N rows of a resource |

</details>

<details>
<summary><b>Data Quality</b> (3 tools)</summary>

| Tool | Description |
|------|-------------|
| `check_freshness` | Check if a dataset is current vs. its update schedule |
| `profile_data` | Statistical profile using DuckDB SUMMARIZE |
| `validate_result` | Validate that a data claim is supported by query results |

</details>

<details>
<summary><b>Geospatial</b> (3 tools)</summary>

| Tool | Description |
|------|-------------|
| `load_geodata` | Cache a geospatial resource (SHP, KML, GeoJSON) into DuckDB |
| `spatial_query` | Run spatial queries against cached geospatial data |
| `list_geo_datasets` | Find datasets containing geospatial resources |

</details>

## MCP Resources

Resources the agent can read for context without calling a tool:

| URI | Description |
|-----|-------------|
| `ontario://cache/index` | List of all locally cached datasets with freshness info |
| `ontario://dataset/{dataset_id}` | Full metadata for a specific dataset (supports prefixed IDs) |
| `ontario://portal/stats` | Overview statistics across all data portals |
| `ontario://schema/{table_name}` | Column schema, types, sample values, and type warnings for a cached table |
| `ontario://guides/duckdb-sql` | DuckDB SQL reference for Ontario open data analysis |

## Prompts

Context-aware guided workflow prompts:

- **`explore_topic`** — Guided exploration of a topic (fetches live catalogue context)
- **`data_investigation`** — Deep dive into a specific dataset: schema, quality, statistics
- **`compare_data`** — Side-by-side analysis of multiple datasets

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `ONTARIO_DATA_CACHE_DIR` | `~/.cache/ontario-data` | DuckDB storage + log file location |
| `ONTARIO_DATA_TIMEOUT` | `30` | HTTP timeout in seconds |
| `ONTARIO_DATA_RATE_LIMIT` | `10` | Max CKAN requests per second |

## Development

```bash
uv sync
uv run python -m pytest tests/ -v
```

## License

MIT — see [LICENSE](LICENSE) for the software.

Data accessed through this tool is provided under the following open government licences:

- Contains information licensed under the [Open Government Licence – Ontario](https://www.ontario.ca/page/open-government-licence-ontario).
- Contains information licensed under the [Open Government Licence – Toronto](https://open.toronto.ca/open-data-licence/).
- Contains information licensed under the [Open Government Licence – City of Ottawa](https://open.ottawa.ca/pages/open-data-licence).
