Civic AI Tools

Use AI to explore NYC Open Data and Google Data Commons — no advanced programming required.

Civic AI Tools connects AI assistants (GitHub Copilot, Cursor, Claude Code) to public datasets using the Model Context Protocol (MCP). Think of MCP as a universal adapter that lets AI talk directly to data sources — so you can ask questions in plain English and get answers from real civic data.

Built for civic technologists, government workers, journalists, and students exploring public data with AI.

Civic AI Tools sits at one layer of a broader landscape where open data meets AI: projects in this space address making data discoverable to AI, making AI mediation legible to humans, feeding signal back to data publishers, and orchestrating AI across civic-data domains. This project focuses on the second layer — evidence packages that make AI analyses inspectable, reproducible, and cryptographically verifiable. See docs/research/landscape-analysis.md for the wider landscape.

What can you do with this?

• Ask questions about NYC 311 complaints, restaurant inspections, or housing violations in plain English
• Pull population, income, and demographic data from Google Data Commons
• Generate visualizations and dashboards from live civic datasets
• Compare statistics across cities and time periods

Example queries you can ask:

• "What are the top 311 complaint types in NYC?"
• "Show me restaurant inspection grades by borough"
• "Compare NYC's population trend with Los Angeles and Chicago"

Quick start

Option 1: GitHub Codespaces (recommended — nothing to install)

1. Click the "Open in GitHub Codespaces" button above
2. Wait for the environment to build (everything is installed automatically)
3. Open Copilot Chat (sidebar chat icon or Ctrl+Shift+I), switch to Agent mode, and start asking questions

Optional: For higher rate limits, add Codespaces Secrets before launching:

• Go to your fork's Settings > Secrets and variables > Codespaces
• Add SOCRATA_APP_TOKEN (get one free)
• Add DC_API_KEY (get one free) — required for Data Commons

Without API keys, NYC Open Data queries still work (with lower rate limits). Data Commons is skipped if no key is set.

Option 2: Local setup

git clone https://github.com/npstorey/civic-ai-tools.git
cd civic-ai-tools
cp .env.example .env       # Add your API keys (see file for instructions)
./scripts/setup.sh         # Builds MCP servers and generates config files

Then open the project in your preferred tool:

• VS Code + Copilot — Reload window (Ctrl+Shift+P > "Developer: Reload Window"), use Copilot Chat in Agent mode
• Cursor — Open the folder in Cursor (restart if MCP servers don't appear)
• Claude Code — Run claude in this directory and approve the MCP servers when prompted

See docs/setup.md for detailed instructions and troubleshooting.

What's included

Requirements (local setup only)

• Node.js 18+
• Python 3.11+
• uv (recommended) — install with curl -LsSf https://astral.sh/uv/install.sh | sh

Example scripts

The examples/ directory contains standalone scripts you can run directly with uv:

uv run examples/real_data_analysis.py         # Fetch and analyze live NYC + Data Commons data
uv run examples/nyc_311_dashboard.py          # Launch a Streamlit dashboard of 311 data
uv run examples/create_html_visualizations.py # Generate an interactive HTML dashboard

See examples/README.md for the full list.

Related projects

Documentation

Getting started

• docs/setup.md — Setup, tool-specific instructions, and troubleshooting
• docs/publish-evidence.md — Publishing analyses from Claude Code to the evidence registry

Data and skills

• docs/mcp-servers.md — Directory of civic data MCP servers
• docs/datasets.md — Curated dataset directory
• docs/opengov-skill.md — Socrata query patterns and SoQL syntax reference
• docs/skills/ — Per-source AI skill guidance

Governance and discipline

• ROADMAP.md — Public roadmap, trust commitments, and out-of-scope items
• docs/adr/ — Architectural decision records
• docs/trust-and-evidence.md — What "verifiable" means and how to verify a package
• docs/sustainability.md — Project sustainability posture

Architecture

• docs/architecture/ — Canonical architecture documents and spec drafts (internal working drafts; not stable specs)
• docs/architecture/end-state-vision.md — Layered architecture target with build-state coloring and full glossary
• docs/architecture/open-evidence-standard.md — Internal working draft of the Open Evidence Standard (pre-v0.1)
• docs/architecture/civic-claim-vocabulary-draft-spec.md — Internal working draft of the Civic Claim Vocabulary, the typed-claims layer (pre-v0.1)
• docs/architecture/xanadu-doctrine.md — Project discipline gating spec growth
• docs/architecture/open-questions.md — Open questions registry. Canonical home for unresolved decisions affecting the architecture and standards. Start here when deciding what's settled vs. what's still in flight.

Research

• docs/research-agenda.md — Research questions the project engages
• docs/research/landscape-analysis.md — Ecosystem survey of adjacent civic-AI and evidence projects
• docs/evidence-protocol-fork.md — Long-form analysis of the evidence-system fork
• docs/research/ — Additional research artifacts

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines — there are ways to help even if you don't write code.

Glossary

New to some of these terms? Here's a quick reference:

Disclaimer

This is a personal project and is not affiliated with, endorsed by, or representative of any employer or organization.