permit-data-mcp-server by ChrisTansey007 - 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

check_permit_data - Data freshness verification
download_permits - Complete permit dataset download
get_recent_permits - Incremental data fetching
enrich_with_contacts - Contact information enrichment
run_pipeline - End-to-end data processing workflow
filter_permits_by_date - Date range filtering
filter_permits - Custom expression filtering
permit_stats_summary - Statistical analysis and grouping
geocode_permit_addresses - Address geocoding
get_current_subcontractors - Subcontractor list retrieval
update_current_subcontractors - Subcontractor management
get_contacts_for_permit - Individual permit contact lookup
generate_contact_payload - Communication template generation
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

Clone the repository:

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

Install dependencies:
```
pip install -r requirements.txt
```

Configure environment:

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

Run the server:
```
python permit_mcp_server.py
```

Docker Deployment

Using Docker Compose (Recommended):
```
docker-compose up -d
```

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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

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

🆘 Support

For issues, questions, or contributions:

Check existing GitHub Issues
Create a new issue with detailed description
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