megan-arellano/mcp-denver-open-data

Denver Geospatial Data MCP Server

A Model Context Protocol (MCP) server that provides access to Denver's Open Data catalog. This server allows you to search and download datasets from Denver's collection of geospatial data directly from your IDE. This project was vibe coded with GitHub Copilot as a proof of concept.

Features

• Search Datasets: Find datasets using natural language queries
• Format Filtering: Filter results by data format (CSV, GeoJSON, Shapefile, etc.)
• Download Information: Get direct download URLs for datasets
• Recent Data: Filter datasets by modification date
• Rich Metadata: Access dataset descriptions, publishers, themes, and keywords

Installation

Prerequisites

• Ruby 2.7 or higher
• Bundler gem

Setup

1. Clone the repository:

   git clone <repository-url>
   cd agent
   

2. Install dependencies:

   bundle install
   

3. Test the installation:

   ruby test/denver_geospatial_client_test.rb
   ruby test/utils_test.rb
   

IDE Configuration

VS Code with GitHub Copilot

Add this server to your MCP configuration file:

Location: ~/Library/Application Support/Code/User/mcp.json (macOS) or similar path on other platforms

{
  "servers": {
    "denver-open-data": {
      "command": "ruby",
      "type": "stdio",
      "args": ["/path/to/your/cloned/agent/bin/denver_geospatial_server.rb"]
    }
  }
}

Replace /path/to/your/cloned/agent/ with the actual path where you cloned this repository.

Alternative: Direct Executable (requires chmod)

If you prefer to make the script directly executable:

chmod +x bin/denver_geospatial_server.rb

Then use this simpler configuration:

{
  "servers": {
    "denver-open-data": {
      "command": "/path/to/your/cloned/agent/bin/denver_geospatial_server.rb",
      "type": "stdio"
    }
  }
}

Other IDEs

For IDEs that support MCP servers, use the same configuration pattern:

• Type: stdio
• Command: ruby
• Arguments: ["/path/to/agent/bin/denver_geospatial_server.rb"]

Or with direct executable (after chmod +x):

• Type: stdio
• Command: Full path to bin/denver_geospatial_server.rb
• Arguments: None required

Usage Examples

Once configured, you can use the server through your IDE's AI assistant:

Search for Datasets

• "Find datasets about parks in Denver"
• "Search for crime data in CSV format"
• "Show me recent transportation datasets"

Download Datasets

• "Get download information for dataset ID abc123"
• "Download the parks dataset in GeoJSON format"

Available Tools

search_datasets

Search Denver's geospatial data catalog.

Parameters:

• query (required): Search terms (e.g., "parks", "traffic", "zoning")
• format (optional): Filter by format ("CSV", "GeoJSON", "Shapefile", etc.)
• updated_within_days (optional): Only show datasets updated within N days
• limit (optional): Maximum results (1-100, default 20)

download_dataset

Get download information for a specific dataset.

Parameters:

• dataset_id (required): Dataset ID from search results
• format (optional): Preferred download format

Data Formats Supported

• CSV
• GeoJSON
• JSON
• Shapefile (SHP)
• Excel (XLSX)
• KML
• PDF

Development

Running Tests

ruby test/denver_geospatial_client_test.rb
ruby test/utils_test.rb

Project Structure

agent/
├── bin/
│   └── denver_geospatial_server.rb    # MCP server executable
├── lib/
│   ├── denver_geospatial_client.rb    # Main client library
│   └── utils.rb                       # Utility functions
├── test/                              # Test suite
├── Gemfile                           # Ruby dependencies
└── README.md                         # This file

Troubleshooting

Common Issues

1. "Command not found" error:

   • If using direct executable: Ensure the script is executable with chmod +x bin/denver_geospatial_server.rb
   • If using Ruby command: Verify Ruby is installed and in PATH with ruby --version
   • Verify the full path in your MCP configuration

2. "Load error" when starting:

   • Run bundle install to ensure all dependencies are installed
   • Check that Ruby version is 2.7 or higher: ruby --version

3. No search results:

   • Try broader search terms
   • Check if the Denver Open Data API is accessible
   • Verify network connectivity

Debug Mode

To run the server with debug output:

DEBUG=1 ruby bin/denver_geospatial_server.rb

Or if using executable version:

DEBUG=1 ./bin/denver_geospatial_server.rb

API Information

This server connects to Denver's Open Data DCAT-AP 2.0.1 feed:

• Base URL: https://opendata-geospatialdenver.hub.arcgis.com/api/feed/dcat-ap/2.0.1
• Format: DCAT-AP (Data Catalog Vocabulary Application Profile)
• Update Frequency: Real-time from Denver's data portal

License

[Add your license information here]

Contributing

[Add contribution guidelines here]