ChrisTansey007/permit-data-mcp-server

PermitData MCP Server

A comprehensive FastMCP server providing 14 JSON-schema-driven tools for permit data management, contact enrichment, analytics, and report generation for Brunswick County NC permit systems.

🚀 Features

Core Capabilities

• Data Freshness Checking - Verify if local permit data is up-to-date
• Full & Incremental Data Fetching - Download complete permit datasets or recent changes
• Contact Enrichment - Automatically attach contractor and owner contact information
• Pipeline Orchestration - Combined download, processing, and enrichment workflows
• Advanced Filtering & Analytics - Date-based filtering, custom expressions, and statistical summaries
• Geocoding Support - Convert permit addresses to coordinates
• Subcontractor Management - CRUD operations for tracking current subcontractors
• Report Generation - Multiple output formats (Markdown, Word, CSV)
• Communication Payloads - Generate templated messages for stakeholder outreach

Available Tools

1. check_permit_data - Data freshness verification
2. download_permits - Complete permit dataset download
3. get_recent_permits - Incremental data fetching
4. enrich_with_contacts - Contact information enrichment
5. run_pipeline - End-to-end data processing workflow
6. filter_permits_by_date - Date range filtering
7. filter_permits - Custom expression filtering
8. permit_stats_summary - Statistical analysis and grouping
9. geocode_permit_addresses - Address geocoding
10. get_current_subcontractors - Subcontractor list retrieval
11. update_current_subcontractors - Subcontractor management
12. get_contacts_for_permit - Individual permit contact lookup
13. generate_contact_payload - Communication template generation
14. generate_reports - Multi-format report creation

📋 Prerequisites

• Python 3.8 or higher
• Access to Brunswick County permit APIs
• Valid API endpoints (configured in environment)

🛠️ Installation

Local Development

1. Clone the repository:

   git clone https://github.com/YOUR_USERNAME/permit-data-mcp-server.git
   cd permit-data-mcp-server
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your specific configuration
   

4. Run the server:

   python permit_mcp_server.py
   

Docker Deployment

1. Using Docker Compose (Recommended):

   docker-compose up -d
   

2. Using Docker directly:

   docker build -t permit-mcp-server .
   docker run -p 8000:8000 --env-file .env permit-mcp-server
   

⚙️ Configuration

Environment Variables

Create a .env file based on .env.example:

# Data Directory
DATA_DIR=/tmp/permit_mcp

# Brunswick County API Endpoints
PERMIT_FEATURESERVER_URL_PRIMARY=https://bcgis.brunswickcountync.gov/arcgis/rest/services/Permitting/Permit_Locations/FeatureServer/0/query
PERMIT_FEATURESERVER_URL_SECONDARY=https://services1.arcgis.com/W6gamXPYQeLXrdAd/arcgis/rest/services/Permit_Locations/FeatureServer/0/queryPROJECT_SEARCH_API_URL=https://etrakit.brunswickcountync.gov/eTRAKiT3/Search/Project/DoSearch
CONTRACTOR_KEY_API_URL=https://etrakit.brunswickcountync.gov/eTRAKiT3/Search/Permit/GetContractorKey
CONTRACTOR_CONTACT_API_URL=https://etrakit.brunswickcountync.gov/eTRAKiT3/Search/Contractor/GetContacts

# File Paths
SUBSCRIBER_STATE_PATH=${DATA_DIR}/current_subs.json
REPORTS_OUTPUT_DIR=${DATA_DIR}

# Security (Optional)
MCP_API_KEY=your_secret_api_key_here

API Endpoints

The server integrates with multiple Brunswick County systems:

• ArcGIS FeatureServer - Primary permit data source
• eTRAKiT Project Search - Project lookup and validation
• eTRAKiT Contractor APIs - Contact information retrieval

📖 Usage Examples

Basic Data Fetching

# Check if local data needs updating
result = check_permit_data(
    base_url="https://your-arcgis-endpoint.com/query",
    local_csv="/path/to/permits.csv",
    delta_days=1
)

# Download fresh permit data
permits = download_permits(
    base_url="https://your-arcgis-endpoint.com/query",
    out_csv="/path/to/permits.csv"
)

Contact Enrichment

# Enrich permits with contractor contacts
enriched = enrich_with_contacts(
    permit_csv="/path/to/permits.csv"
)

# Or use DataFrame directly
enriched = enrich_with_contacts(
    permit_df=permits_data
)

Filtering and Analytics

# Filter by date range
recent_permits = filter_permits_by_date(
    permits_json=permits_data,
    start="2024-01-01",
    end="2024-12-31",
    date_field="IssueDate"
)

# Generate statistics
stats = permit_stats_summary(
    permits_json=permits_data,
    group_by="ContractorKey"
)

Report Generation

# Generate multiple report formats
reports = generate_reports(
    df_json=permits_data,
    group_label="Q4_2024",
    formats=["markdown", "word", "csv"]
)

🧪 Testing

Run the test suite:

# Run all tests
python -m pytest test_permit_server.py -v

# Run specific test category
python -m pytest test_permit_server.py::TestDataFiltering -v

# Run with coverage
pip install pytest-cov
python -m pytest test_permit_server.py --cov=permit_mcp_server

📁 Project Structure

permit-data-mcp-server/
├── permit_mcp_server.py       # Main FastMCP server application
├── requirements.txt           # Python package dependencies
├── .env.example              # Environment configuration template
├── Dockerfile                # Container build configuration
├── docker-compose.yml        # Multi-container orchestration
├── .gitignore               # Git version control ignore rules
├── test_permit_server.py     # Comprehensive test suite
├── LICENSE                   # MIT License
├── README.md                 # Project documentation (this file)
└── data/                     # Runtime data directory
    ├── permits_latest.csv    # Downloaded permit data
    ├── current_subs.json     # Subcontractor state
    └── reports/              # Generated reports

🔧 API Reference

Tool Categories

Data Management

• check_permit_data - Verify data freshness and synchronization status
• download_permits - Full dataset download with optional caching
• get_recent_permits - Incremental updates based on edit timestamps

Processing & Enrichment

• enrich_with_contacts - Attach contractor contact information
• run_pipeline - Automated end-to-end processing workflow
• geocode_permit_addresses - Convert addresses to geographic coordinates

Filtering & Analytics

• filter_permits_by_date - Time-based data filtering
• filter_permits - Custom expression-based filtering
• permit_stats_summary - Statistical analysis and grouping operations

State Management

• get_current_subcontractors - Retrieve tracked subcontractor list
• update_current_subcontractors - Add/remove subcontractors from tracking

Communication & Reporting

• get_contacts_for_permit - Individual permit contact lookup
• generate_contact_payload - Template-based message generation
• generate_reports - Multi-format report creation (MD, Word, CSV)

🚦 Health Monitoring

The server includes built-in health checks:

• HTTP Endpoint: GET /health
• Docker Health Check: Automatic container health monitoring
• Logging: Comprehensive request tracking with correlation IDs

🤝 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

For issues, questions, or contributions:

1. Check existing GitHub Issues
2. Create a new issue with detailed description
3. Include logs and configuration details (sanitized)

🔗 Related Projects

• FastMCP Framework - The underlying MCP server framework
• Brunswick County GIS - Data source documentation

Built with FastMCP | Supports MCP Protocol | Production Ready