ChrisTansey007/permit-data-mcp-server-nhc

PermitData FastMCP Server - New Hanover County (NHC)

A comprehensive FastMCP server providing 8 specialized tools for managing New Hanover County building permit data through ArcGIS Feature Services integration.

🚀 Quick Start

# Clone the repository
git clone https://github.com/yourusername/permit-data-mcp-server-nhc.git
cd permit-data-mcp-server-nhc

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Run the server
python permit_mcp_server_nhc.py

The server will start at http://localhost:8000/mcp

📋 Features

Data Management

• check_permit_data: Verify data freshness and compare local vs server records
• download_permits: Fetch all permits with intelligent caching and pagination
• get_recent_permits: Retrieve permits based on date criteria

Analytics & Filtering

• filter_permits: Apply Python expressions to filter permit datasets
• permit_stats_summary: Generate statistical summaries grouped by specified fields

State Management

• get_current_subcontractors: Retrieve cached subcontractor list
• update_current_subcontractors: Add/remove subcontractors from persistent state

Reporting

• generate_reports: Create markdown and CSV reports with timestamped outputs

🛠 Configuration

Environment Variables

Create a .env file from .env.example and configure:

# Data storage
DATA_DIR=./data

# New Hanover County ArcGIS endpoints
PERMIT_FEATURESERVER_URL_PRIMARY=https://gis.nhcgov.com/server/rest/services/Thematic/BuildingPermits/FeatureServer/0/query

# State management
SUBSCRIBER_STATE_PATH=./data/current_subs.json
REPORTS_OUTPUT_DIR=./data

# Optional API authentication
# MCP_API_KEY=your_secure_api_key_here

# Server configuration
PORT=8000

Required Dependencies

• fastmcp >=0.1.0: FastMCP framework
• pandas >=2.0.0: Data manipulation and analysis
• requests >=2.31.0: HTTP client for API calls
• python-dateutil >=2.8.2: Date parsing utilities
• python-dotenv >=1.0.0: Environment variable management

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Build and start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Using Docker Directly

# Build the image
docker build -t permit-mcp-server-nhc .

# Run the container
docker run -d \
  --name permit-mcp-nhc \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  permit-mcp-server-nhc

📖 API Reference

Tool: check_permit_data

Verify data freshness and synchronization status.

Parameters:

• base_url (str): ArcGIS Feature Service URL
• local_csv (str): Path to local CSV file for comparison
• delta_days (int, default=1): Days threshold for staleness check
• strict (bool, default=False): Raise exceptions on errors

Returns:

{
  "is_stale": true,
  "server_record_count": 1250,
  "server_last_edit": "2025-01-15T10:30:00",
  "local_record_count": 1245,
  "local_last_modified": "2025-01-14T15:20:00",
  "reason": "stale counts / age"
}

Tool: download_permits

Fetch all permits with intelligent caching and pagination.

Parameters:

• base_url (str): ArcGIS Feature Service URL
• force (bool, default=False): Force download even if cache is fresh
• where (str, default="1=1"): SQL WHERE clause for filtering
• page_size (int, default=10000): Records per API request
• out_csv (str, optional): Output CSV path for caching

Returns:

{
  "records": 1250,
  "csv_path": "./data/permits.csv",
  "dataframe": [...],
  "skipped": false
}

Tool: get_recent_permits

Retrieve permits based on date criteria.

Parameters:

• base_url (str): ArcGIS Feature Service URL
• since (str): ISO date string (required)
• date_field (str, default="ISSUE_DATE"): Date field to filter on
• page_size (int, default=10000): Records per API request

Tool: filter_permits

Apply Python expressions to filter permit datasets.

Parameters:

• permits_json (List[Dict]): Permit records to filter
• filter_expr (str): Python expression (e.g., "row['PERMIT_VALUE'] > 50000")

Tool: permit_stats_summary

Generate statistical summaries grouped by specified fields.

Parameters:

• permits_json (List[Dict]): Permit records to analyze
• group_by (str, default="GENERAL_CONTRACTOR"): Field to group by

🧪 Testing

Run the test suite with pytest:

# Install test dependencies
pip install pytest

# Run all tests
pytest test_permit_server.py -v

# Run with coverage
pip install pytest-cov
pytest test_permit_server.py --cov=permit_mcp_server_nhc

📁 Project Structure

permit-data-mcp-server-nhc/
├── permit_mcp_server_nhc.py    # Main FastMCP server
├── requirements.txt            # Python dependencies
├── .env.example               # Environment template
├── Dockerfile                 # Container configuration
├── docker-compose.yml         # Docker orchestration
├── test_permit_server.py      # Test suite
├── README.md                  # This file
├── LICENSE                    # MIT License
├── .gitignore                # Git ignore rules
├── data/                     # Runtime data storage
└── logs/                     # Application logs

🔧 Development

Local Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt
pip install pytest pytest-cov black flake8

# Format code
black .

# Lint code
flake8 permit_mcp_server_nhc.py

# Run server in development mode
python permit_mcp_server_nhc.py

Data Source Information

This server connects to New Hanover County's public ArcGIS Feature Service:

• Service URL: https://gis.nhcgov.com/server/rest/services/Thematic/BuildingPermits/FeatureServer/0
• Data Type: Building permits issued by New Hanover County
• Update Frequency: Real-time (as permits are processed)
• Geographic Coverage: New Hanover County, North Carolina

Note: Unlike Brunswick County, New Hanover County does not expose public EnerGov/COAST endpoints for contractor contact information.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🆘 Support

• Issues: Report bugs or request features via GitHub Issues
• Documentation: FastMCP documentation at https://github.com/jlowin/fastmcp
• Data Source: New Hanover County GIS portal

🔗 Related Projects

• Brunswick County Permit MCP Server - Original template
• FastMCP Framework - Underlying MCP framework

Built with ❤️ using FastMCP for New Hanover County permit data management.