briandconnelly/seattle-open-data

0 stars 0 forks Quality 78 Trend 20MIT

Agent-friendly MCP server for Seattle Open Data: search, describe, and query data.seattle.gov datasets

Overview

An agent-friendly MCP server for Seattle Open Data (Socrata SODA2). All four tools work against the live portal, with curated guides for seven flagship datasets. See evals/results for the agent evaluation. The server runs over stdio. The uvx commands below need uv. download seattle-open-data- .mcpb from the latest release and open it with Claude Desktop. run uvx seattle-open-data as a stdio server: set SOCRATA_APP_TOKEN to use a Socrata application token, for example claude mcp add seattle-open-data -e SOCRATA_APP_TOKEN=... -- uvx seattle-open-data. The bundle asks for it in Claude Desktop's settings. A rejected token is reported as app_token_rejected, never silently dropped. To build the MCPB bundle locally (needs the mcpb CLI): make mcpb. Tag vX.Y.Z after bumping the version: the release workflow builds and smoke-tests the wheel, sdist, and .mcpb, publishes to PyPI after maintainer approval, and attaches all three to a GitHub Release. See docs/releasing.

README

seattle-open-data

An agent-friendly MCP server for Seattle Open Data (Socrata SODA2).

Status: alpha (0.2.0). All four tools work against the live portal, with curated guides for seven flagship datasets. See evals/results for the agent evaluation.

Tools

Tool	Purpose
`seattle_data_search_datasets`	Find datasets by topic
`seattle_data_describe_dataset`	Columns, row count, time coverage, place fields, geo columns
`seattle_data_query_dataset`	Bounded reads and aggregates (SoQL clauses or raw SoQL)
`seattle_data_get_reference`	Capability summary, SoQL help, guides, error catalog

Install

The server runs over stdio. The uvx commands below need uv.

Claude Desktop: download seattle-open-data-.mcpb from the latest release and open it with Claude Desktop.

Claude Code:

claude mcp add seattle-open-data -- uvx seattle-open-data

Codex:

codex mcp add seattle-open-data -- uvx seattle-open-data

Any other MCP client: run uvx seattle-open-data as a stdio server:

{
  "mcpServers": {
    "seattle-open-data": { "command": "uvx", "args": ["seattle-open-data"] }
  }
}

Optional app token: set SOCRATA_APP_TOKEN to use a Socrata application token, for example claude mcp add seattle-open-data -e SOCRATA_APP_TOKEN=... -- uvx seattle-open-data. The bundle asks for it in Claude Desktop’s settings. A rejected token is reported as app_token_rejected, never silently dropped.

Develop

From a checkout:

uv sync
uv run seattle-open-data                                  # run the server over stdio
uv run pytest
uv run ruff check && uv run ruff format --check && uv run ty check
UPDATE_SNAPSHOTS=1 uv run pytest tests/test_contract.py   # after an intended tool-surface change
uv run pytest --run-integration -m integration            # live tests against data.seattle.gov
uv run python evals/run.py [--host claude|codex]  [task_id ...]
uv run python evals/report.py  --answers

To build the MCPB bundle locally (needs the mcpb CLI): make mcpb.

Release

Tag vX.Y.Z after bumping the version: the release workflow builds and smoke-tests the wheel, sdist, and .mcpb, publishes to PyPI after maintainer approval, and attaches all three to a GitHub Release. See docs/releasing.md for the steps, the TestPyPI rehearsal, and one-time setup.

License

MIT

View this README on GitHub

Install

uvx seattle-open-data

Configuration

{
  "mcpServers": {
    "seattle-open-data": { "command": "uvx", "args": ["seattle-open-data"] }
  }
}