README.md

metadata

title: FixMyNeighborhood App
emoji: 🏙️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
tags:
  - mcp-in-action-track-enterprise
  - mcp-in-action-track-consumer
  - mcp-in-action-track-customer
  - mcp-in-action-track-creative
  - agents
  - mcp-client
  - multi-agent
  - smolagents

FixMyNeighborhood - Multi-Agent AI Infrastructure Reporter

Potholes cause thousands of cyclist injuries yearly, and broken streetlights leave most public-housing residents feeling unsafe at night. That's why we built FixMyNeighborhood—an AI-powered system that makes reporting these problems simple and fast.

FixMyNeighborhood is an autonomous multi-agent AI platform that helps NYC residents report infrastructure problems—potholes, broken streetlights, blocked drains—directly to the city. Powered by a Full Multi-Agent Controller (MAC) architecture, it handles the paperwork, follow-ups, and routing automatically.

You simply describe the issue—our AI agents take care of the bureaucracy.

Demo

Watch Demo Video

Social Media

X Post

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Gradio UI (app.py)                       │
│                   Streaming + Real-time Updates                 │
└─────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │   Security Layer        │
                    │  Rate Limit │ Validation│
                    │  Prompt Guard │ Masking │
                    └────────────┬────────────┘
                                 │
┌─────────────────────────────────────────────────────────────────┐
│              Autonomous Controller (Claude Sonnet)              │
│                                                                 │
│   FULL AUTONOMY: Plans → Reasons → Delegates → Self-Evaluates  │
└─────────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
    ┌────────────┐       ┌────────────┐       ┌────────────┐
    │ 🎯 Triage  │       │ 🔍 Research│       │ 📋 Report  │
    │   Agent    │       │   Agent    │       │   Agent    │
    │  (Haiku)   │       │  (Haiku)   │       │  (Haiku)   │
    └────────────┘       └────────────┘       └────────────┘
           │                    │                    │
           └────────────────────┼────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    │     MCP Server        │
                    │      (8 Tools)        │
                    │                       │
                    │  Weather.gov (real)   │
                    │  Photon/OSM (real)    │
                    │  NYC Open Data (real) │
                    └───────────────────────┘

Quickstart

1. Run on HuggingFace Spaces

Visit: FixMyNeighborhood Space

2. Local Development

# Clone
git clone https://huggingface.co/spaces/MCP-1st-Birthday/fixmyneighborhood-app
cd fixmyneighborhood-app

# Install
pip install -r requirements.txt

# Configure
export ANTHROPIC_API_KEY=your_key_here

# Run
python app.py

3. Example Session

User: "There's a huge pothole on Broadway near Times Square"

🎯 Triage Agent
  └─ Geocoding Address → ✓ Manhattan, NYC

🔍 Research Agent
  └─ Looking Up City Records → RD-MN-0042, 3 complaints
  └─ Checking Nearby Reports → 2 reports (1 open)
  └─ Getting Weather → 45°F, Clear

📋 Report Agent
  └─ Getting Department Info → DOT (24-48h response)
  └─ Generating PDF Report → 📄 FMN-20251129

---
Report ID: FMN-20251129-001
Priority: Medium
Department: NYC DOT
Expected Response: 24-48 hours

Key Features

Feature	Description
Autonomous Controller	Claude Sonnet makes ALL decisions - plans, reasons, delegates
3 Specialized Workers	Triage, Research, Report agents (Claude Haiku)
8 MCP Tools	Real APIs (Weather.gov, Photon, NYC Open Data)
Multi-turn Conversation	Controller maintains context across messages
Image Analysis	Claude Vision identifies infrastructure issues from photos
Real-time Streaming	See agent progress as it happens

MCP Tools

Tool	Description	Data Source
geo_search_address	Geocode addresses to coordinates	Photon API (OpenStreetMap)
validate_address	Validate NYC addresses	NYC GeoSearch API
cityinfra_lookup_asset	Look up infrastructure assets	NYC Open Data (DOT)
get_nearby_reports	Find nearby 311 reports	NYC 311 Open Data
weather_get_current	Get current weather conditions	Weather.gov (NOAA)
get_department_info	Get responsible department & SLA	NYC 311 SLA Data
pdf_generate_report	Generate PDF report	ReportLab (local)
sendgrid_send_email	Send email notification	Resend API

Tech Stack

Component	Technology
UI Framework	Gradio 6.0
Agent Framework	smolagents (HuggingFace)
LLM Provider	Anthropic Claude (via LiteLLM)
Controller Model	Claude Sonnet 4.5
Worker Models	Claude Haiku 4.5
Maps	Folium (Leaflet.js)
Tool Protocol	Model Context Protocol (MCP)

Security

Layer	Protection
Rate Limiting	Per-session sliding window (prevents abuse)
Input Validation	Length limits, HTML/XSS detection
Prompt Injection	Pattern detection for jailbreaks
Cross-User Isolation	gr.State per-session (no data leakage)
Output Masking	PII anonymization in logs
Error Handling	User-friendly messages, no stack traces exposed

Geographic validation is handled by MCP tools (validate_address, geo_search_address) using real NYC APIs.

Project Structure

fixmyneighborhood-app/
├── app.py                    # Gradio UI entry point
├── config.py                 # Environment config
│
├── agents/                   # Multi-agent system
│   ├── controller.py         # Autonomous MAC (Claude Sonnet)
│   ├── subagents.py          # Worker definitions (Claude Haiku)
│   ├── prompts.py            # System prompts
│   ├── reasoning.py          # ReasoningTrace for observability
│   └── thought_parser.py     # Parse agent thinking/tool calls
│
├── core/                     # Core utilities
│   ├── session.py            # Session management
│   ├── events.py             # Event types and handling
│   └── image_analysis.py     # Claude Vision integration
│
├── tools/                    # MCP integration
│   ├── mcp_client.py         # MCP server client
│   └── mcp_tools.py          # smolagents tool wrappers
│
├── security/                 # Security layer
│   ├── rate_limiter.py       # Per-session rate limiting
│   ├── input_validator.py    # Input sanitization
│   ├── prompt_guard.py       # Prompt injection detection
│   ├── output_masker.py      # PII masking
│   └── error_handler.py      # Friendly error messages
│
├── observability/            # Logging & tracing
│   ├── structured_logger.py  # JSON-friendly logging
│   ├── decision_tracker.py   # Agent decision tracking
│   └── audit_trail.py        # Request lifecycle audit
│
├── ui/                       # UI utilities
│   ├── mapping.py            # Folium map display
│   ├── logging.py            # Log capture & parsing
│   ├── chat_messages.py      # Chat message formatting
│   └── timeline.py           # Agent execution timeline
│
└── docs/                     # Detailed documentation
    ├── architecture.md       # Full architecture details
    ├── security.md           # Security deep-dive
    ├── ux.md                 # UX & streaming
    └── observability.md      # Logging & tracing

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Anthropic API key
MCP_SERVER_URL	No	MCP server URL (defaults to HF Spaces)
GRADIO_THEME	No	UI theme (default: gstaff/xkcd)

Documentation

• Architecture - Controller, subagents, MCP tools
• Security - Rate limiting, validation, isolation
• UX - Streaming, error handling, traceability
• Observability - Logging, decision tracking
• Optional Enhancements - Self-eval, confidence scores

Hackathon

Track 2: MCP in Action - Full-autonomous multi-agent system with MCP tools for real-world citizen value.

License

MIT