mcp-hackathon

bvorland/mcp-hackathon

3.1

If you are the rightful owner of mcp-hackathon and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

FastMCP server for UK community analysis using government data sources.

Tools
3
Resources
0
Prompts
0

Community Strategy Agent

FastMCP server for UK community analysis using government data sources.

Overview

Integrates data from five UK government datasets:

  • ONS - Census 2021 demographic data
  • Nomis - Labour market and employment statistics
  • IMD 2019 - Index of Multiple Deprivation rankings
  • DEFRA UK-AIR - Air quality monitoring data
  • Environment Agency - Flood risk and environmental data

Data Sources & Endpoints

  • ONS API: https://api.beta.ons.gov.uk/v1 - Census 2021 population demographics
  • Nomis API: https://www.nomisweb.co.uk/api/v01 - Employment and JSA claimant statistics
  • Postcodes.io: https://api.postcodes.io - Postcode resolution and reverse geocoding
  • DEFRA UK-AIR: https://uk-air.defra.gov.uk/sos-ukair/service - Air quality monitoring stations
  • Environment Agency: https://environment.data.gov.uk - Flood monitoring and water quality
  • IMD 2019: Local CSV file - Index of Multiple Deprivation rankings (32,844 LSOA records)

Known Limitations

  • Geographic Coverage: England and Wales only (Scotland and Northern Ireland not supported)
  • ONS Data: Age breakdowns are estimated from total population by sex
  • Employment Data: Limited postcode-level granularity, uses LSOA/MSOA aggregation
  • Air Quality: Sparse monitoring station coverage, uses nearest station within radius
  • Water Quality: Measurement data may be limited or outdated depending on sampling frequency
  • Rate Limits: API calls use exponential backoff, may experience delays during high usage
  • Data Freshness: Census data from 2021, employment data updated monthly, other sources vary

Installation

Prerequisites

  • Python 3.11+
  • Docker (optional)

Setup

git clone https://github.com/bvorland/mcp-hackathon.git
cd mcp-hackathon

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.\.venv\Scripts\Activate.ps1  # Windows

pip install -r requirements.txt

Usage

Local Development

fastmcp run server.py:mcp --transport http --port 8000 --host 0.0.0.0

Server will be available at http://localhost:8000

Docker

docker build -t mcp-server .
docker run -p 8000:8000 mcp-server

Azure Deployment

az login
azd deploy

API Tools

profile(site, radius_m?)

Generates community profiles for geographic locations.

Parameters:

  • site (string|object): Postcode, place name, or coordinates
  • radius_m (integer, optional): Analysis radius in meters (default: 1000)

Input Examples:

"SW1A 1AA"

{"postcode": "CF10 1EP", "radius_m": 1500}

{"lat": 51.4816, "lon": -3.1791, "radius_m": 2000}

"Birmingham, England"

Returns: Community profile with demographics, employment, deprivation, air quality, and environmental data.

Response Structure:

{
  "site": {
    "lat": 51.4816,
    "lon": -3.1791,
    "postcode": "CF10 1EP",
    "analysis_radius_m": 1000
  },
  "resolved_geography": {
    "lsoa": "E01014398",
    "msoa": "E02006826", 
    "resolved_from": "postcode"
  },
  "demographics": {
    "total_population": 1842,
    "age_0_15": 287,
    "age_16_64": 1344,
    "age_65_plus": 211,
    "gender_split": {"male": 908, "female": 934},
    "data_source": "ONS 2021 Census"
  },
  "employment": {
    "jsa_claimants": 67,
    "economically_active": 1204,
    "unemployment_rate": 4.2,
    "data_source": "Nomis API"
  },
  "deprivation": {
    "imd_rank": 8567,
    "imd_decile": 7,
    "data_source": "IMD 2019"
  },
  "air_quality": {
    "pm25_ug_m3": 11.8,
    "pm10_ug_m3": 17.2,
    "no2_ug_m3": 28.4,
    "data_source": "DEFRA UK-AIR"
  },
  "environmental": {
    "flood_monitoring": {
      "risk_level": "low",
      "nearby_stations": 3
    },
    "water_quality": {
      "sampling_points_nearby": 5,
      "quality_status": "well_monitored"
    }
  },
  "recommended_actions": [...],
  "data_quality": {
    "profile_completeness": "high",
    "ons_data_available": true,
    "nomis_data_available": true
  }
}

datasets()

Returns metadata about integrated data sources including endpoints, coverage, and limitations.

health_check()

Returns server health status and API availability.

File Structure

├── server.py              # FastMCP server implementation
├── requirements.txt       # Python dependencies
├── imd2019.csv           # IMD deprivation data
├── Dockerfile            # Container configuration
├── azure.yaml            # Azure deployment configuration
├── infra/
│   └── main.bicep        # Azure infrastructure
├── LICENSE               # MIT License with disclaimers
└── README.md             # Documentation

Dependencies

  • pandas>=2.0.0 - Data processing
  • fastapi>=0.104.0 - Web framework
  • httpx>=0.25.0 - HTTP client
  • pydantic>=2.0.0 - Data validation
  • uvicorn>=0.24.0 - ASGI server
  • fastmcp>=0.2.0 - MCP framework

License and Disclaimers

This project is licensed under the MIT License - see the file for details.

Important Disclaimers

⚠️ USE AT YOUR OWN RISK ⚠️

  • This software is provided "AS IS" without warranty of any kind
  • The data and analysis should not be used as the sole basis for decision-making
  • Users must verify all data and results independently
  • Consult with relevant professionals before making important decisions
  • The software may contain errors or inaccuracies
  • Authors make no representations regarding accuracy, completeness, or reliability

This software is intended for educational and demonstration purposes only.

Contributing

Please read for security guidelines and development practices.

Security

For security concerns, please review and run python security_check.py before contributing.