Toronto MCP Server: Toronto Open Data Tools

This project implements a Model Context Protocol (MCP) server for Toronto Open Data, deployable on Cloudflare Workers. It exposes a comprehensive set of tools for intelligently querying, analyzing, and retrieving datasets from Toronto's CKAN-powered open data portal, making them accessible to MCP-compatible clients like Claude Desktop, Cursor, and other AI assistants.

🚀 Live Server

Deployed at: https://toronto-mcp.s-a62.workers.dev

SSE Endpoint: https://toronto-mcp.s-a62.workers.dev/sse (for Claude Desktop)
MCP Endpoint: https://toronto-mcp.s-a62.workers.dev/mcp (for other clients)

What does it do?

Provides a remote MCP server exposing tools for Toronto's Open Data via the CKAN API
Intelligently discovers relevant datasets using advanced relevance scoring
Analyzes data freshness patterns with comprehensive update frequency tracking
Provides deep data structure insights including field analysis and schema information
Enables natural language querying of Toronto's 500+ open datasets
Supports comprehensive data analysis combining multiple analytical dimensions

🛠️ Features

Basic CKAN Tools

list_datasets: List all available datasets
search_datasets: Search datasets by keyword
get_package: Retrieve complete metadata for a dataset
get_first_datastore_resource_records: Get records from the first active resource
get_resource_records: Get records from a specific resource by ID

🧠 Advanced Analysis Tools

find_relevant_datasets: Intelligently find and rank datasets using relevance scoring (title, description, tags, organization)
analyze_dataset_updates: Analyze update frequencies with categorization (daily, weekly, monthly, quarterly, annually, irregular)
analyze_dataset_structure: Deep-dive into dataset structure with field definitions, data types, record counts, and optional data previews
get_data_categories: Explore all available organizations and topic groups
get_dataset_insights: Comprehensive analysis combining relevance ranking, update frequency, and data structure insights

💡 Use Cases

For AI Assistants & Researchers

"What traffic data is available in Toronto?" → Ranked datasets with relevance scores and update frequencies
"How current is Toronto's environmental data?" → Update frequency analysis across environmental datasets
"What fields are in the building permits dataset?" → Complete schema analysis with data types and sample records
"Give me insights about Toronto's budget data" → Comprehensive analysis with relevance, freshness, and structure
"Which datasets update daily?" → Frequency-based filtering and categorization

For Data Scientists & Analysts

Discover datasets relevant to specific research questions
Assess data quality and reliability through update patterns
Understand data structure before detailed analysis
Find related datasets across different city departments
Evaluate data completeness and field availability

🏗️ Tech Stack

Cloudflare Workers: Serverless deployment platform
Model Context Protocol (MCP): Standard for AI tool integrations
TypeScript: Type safety and modern development
Zod: Runtime parameter validation
CKAN API: Direct integration with Toronto Open Data

📁 Project Structure

toronto-mcp/
├── src/
│   ├── index.ts                 # MCP server setup and routing
│   └── ckanTools.ts            # Toronto Open Data tools implementation
├── test-runner.ts              # Automated testing framework
├── test-deployment.ts          # Deployment validation script
├── claude-mcp-config.json      # Claude Desktop configuration
├── evaluation-guide.md         # Comprehensive testing strategies
├── example-usage.md            # Usage examples and patterns
├── testing-guide.md            # Automated testing documentation
└── README.md                   # This file

🚀 Quick Start

1. Deploy Your Own Instance

# Clone and deploy
git clone <your-repo>
cd toronto-mcp
npm install
wrangler deploy

2. Test Deployment

# Install testing dependencies
npm install tsx

# Test your deployment
npx tsx test-deployment.ts https://your-worker.workers.dev

3. Connect to Claude Desktop

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "toronto-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://toronto-mcp.s-a62.workers.dev/sse"]
    }
  }
}

Restart Claude Desktop and start asking questions about Toronto's open data!

🧪 Testing & Validation

Quick Connectivity Test

npx tsx test-deployment.ts https://toronto-mcp.s-a62.workers.dev

Automated Testing Framework

# Run mock tests (validates framework)
npm test

# Test specific deployment
npm run test:deployment https://your-url.workers.dev

Manual Testing in Claude Desktop

Try these test queries to verify functionality:

Basic Search: "Find datasets about parking in Toronto"
Update Analysis: "How often does Toronto update traffic data?"
Data Structure: "What fields are in Toronto's building permits data?"
Comprehensive: "Give me insights about Toronto's environmental data"
Categories: "What departments provide open data in Toronto?"

📊 Success Metrics

Your MCP server is working correctly when:

✅ Claude consistently selects appropriate tools for queries
✅ Results include relevance scores and rankings
✅ Update frequency information is categorized correctly
✅ Data structure analysis shows complete field information
✅ Response times are under 10 seconds for complex queries
✅ Error handling provides helpful messages

📚 Documentation

📘 Example Usage Guide

Concrete examples of how to use each MCP tool, including JSON parameters and expected responses. Essential for understanding tool capabilities and integration patterns.

📊 Evaluation & Testing Guide

Comprehensive testing strategies, quality metrics, and evaluation criteria. Includes manual test queries, performance benchmarks, and success metrics for validating MCP server functionality.

🧪 Automated Testing Framework

TypeScript test framework for programmatic validation, performance monitoring, and automated quality assurance. Includes executable test cases and CI/CD integration patterns.

⚙️ Claude Desktop Configuration

Ready-to-use MCP server configuration for Claude Desktop integration.

🎯 Example Tool Usage

Natural Language Queries (via AI Assistant)

"What traffic data is available in Toronto and how current is it?"
"Find housing development datasets with field information"
"Which Toronto datasets update daily?"
"Give me insights about budget and financial data"

Direct Tool Calls (for developers)

// Intelligent dataset discovery
await find_relevant_datasets({
  query: "traffic accidents",
  maxResults: 5,
  includeRelevanceScore: true,
});

// Update frequency analysis
await analyze_dataset_updates({
  query: "transportation",
  groupByFrequency: true,
});

// Complete data structure analysis
await analyze_dataset_structure({
  packageId: "building-permits",
  includeDataPreview: true,
  previewLimit: 10,
});

// Comprehensive insights
await get_dataset_insights({
  query: "housing development",
  maxDatasets: 3,
  includeUpdateFrequency: true,
  includeDataStructure: true,
});

🔧 Available Scripts

npm run dev           # Start development server
npm run deploy        # Deploy to Cloudflare Workers
npm run test          # Run automated tests
npm run test:deployment  # Test specific deployment
npm run lint:fix      # Fix linting issues
npm run format        # Format code

🌟 Key Features

Intelligent Relevance Scoring

Weighted algorithm: Title (10pts) > Description (5pts) > Tags (3pts) > Organization (2pts)
Context-aware ranking: Matches user intent with appropriate datasets
Multi-keyword support: Handles complex queries effectively

Comprehensive Update Analysis

Frequency categorization: Daily, weekly, monthly, quarterly, annually, irregular
Metadata inference: Analyzes patterns when explicit schedules aren't available
Quality assessment: Identifies stale vs. actively maintained datasets

Deep Data Structure Insights

Complete schema analysis: Field names, types, constraints
Record statistics: Counts, completeness, data quality indicators
Sample data: Optional previews for quick assessment
Multi-resource support: Handles datasets with multiple files/formats

🚀 Extending

To add more tools or data sources:

Edit src/ckanTools.ts to add new tool functions
Register new tools in src/index.ts
Update type definitions and validation schemas
Add corresponding tests in the testing framework

Example:

server.tool("new_analysis_tool", { param: z.string() }, async ({ param }) => {
  // Implementation
  return { content: [{ type: "text", text: result }] };
});

🤝 Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass: npm test
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

Built for intelligent open data discovery • Powered by Toronto Open Data & CKAN API • Enhanced for AI assistant integration