<div align="center">

# PermitFlow MCP Server
### Autonomous Portfolio Permitting Intelligence & Pre-Construction Engine

[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Package Manager](https://img.shields.io/badge/UV-Package%20Manager-DE5FE9.svg?style=flat-square)](https://docs.astral.sh/uv/)
[![Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-FF6B6B.svg?style=flat-square)](https://modelcontextprotocol.io/)
[![Architecture](https://img.shields.io/badge/Architecture-FastMCP%20%2B%20Section--Aware%20RAG-4ECDC4.svg?style=flat-square)](https://github.com/modelcontextprotocol/python-sdk)
[![License: ROHIX RB](https://img.shields.io/badge/License-ROHIX%20RB-F1C40F.svg?style=flat-square)](LICENSE)
[![Watch Demo](https://img.shields.io/badge/Demo%20Video-Google%20Drive-FF0000.svg?style=flat-square)](https://drive.google.com/file/d/1j3tYW5fvyOfwpIauRr-qK2_kpjZn-UBb/view?usp=sharing)

<br/>

> **Target Startup**: [PermitFlow](https://www.permitflow.com/) (Y Combinator S22, Series B $54M)  
> **Assignment**: Build an MCP Server for a Real Startup (Individual)  
> **Demo Video**: [Watch Demo on Google Drive](https://drive.google.com/file/d/1Q7kjDj28XWBAHAi5OtZCaVF3Ypx0wF-U/view?usp=sharing)

<br/>

<img src="assets/system_design.png" alt="PermitFlow MCP System Architecture" width="100%" />

</div>

---

## 1. Company Name and Overview

PermitFlow (YC S22, Series B $54M raised) builds software that automates construction permitting for general contractors, commercial developers, and trade subcontractors. The platform streamlines municipal permit research, submittal preparation, and status tracking across US city building departments (AHJs).

---

## 2. The Problem Your Server Solves

Municipal permitting is the primary driver of construction delays in the US (4 to 12 weeks of schedule delay per project). Today:
- High Rejection Rate: Over 40% of permit packets are rejected due to missing exhibits, expired contractor insurance, or absent structural calculations, triggering $500 to $2,000 penalties.
- Manual Comment Resolution: Resolving city examiner objections and writing legal response letters takes days of manual expeditor work.
- Closed SaaS Island: PermitFlow is a closed web dashboard. Estimators and engineers working in Claude Desktop or Cursor cannot interact with permitting data or municipal codes.

Solution: This MCP server acts as an open AI co-pilot alongside PermitFlow, providing pre-flight readiness audits (0-100 GO / NO-GO), building code RAG, and automated PE-sealed response transmittal generation.

---

## 3. Tools, Resources, and Prompts

### Tools (7 Core Intelligence Tools)

| Tool | Role | Function | Rationale |
| :--- | :--- | :--- | :--- |
| `get_daily_manager_briefing` | Management | Health score (0-100), overnight deltas, standup task matrix. | Instant morning visibility across all active portfolio jobs. |
| `intake_project_scope` | Intake Agent | Parses SOW text, detects trades, flags Arizona PE structural triggers. | Automates project intake without manual data entry errors. |
| `estimate_permit_fees_and_sla` | Research Agent | Calculates itemized municipal fees and turnaround SLAs. | Provides accurate upfront budgeting and scheduling. |
| `search_permit_requirements` | Knowledge Engine | BM25 RAG over local codes (Phoenix PMC 301.5, IBC 1609.1, ASHRAE 90.1). | Delivers grounded legal citations without hallucinations. |
| `check_permit_readiness` | Submission Gate | Audits checklist, outputs 0-100 score and GO / NO-GO verdict. | Prevents non-compliant filings and expensive city rejection fees. |
| `generate_formal_ahj_response_packet` | Coordination | Resolves examiner comments into official PE-sealed transmittal letter. | Eliminates 2-3 days of manual response letter drafting. |
| `verify_contractor_registration` | Compliance | Verifies Arizona ROC license standing, Class B-1/CR-11, and $1M insurance. | Prevents administrative rejection from lapsed contractor insurance. |

### Resources (5 Live URI Streams)

| URI | Data Provided | Why Chosen |
| :--- | :--- | :--- |
| `portfolio://summary` | Total active permits, health score, urgent blocker count. | Passive real-time operational context. |
| `portfolio://priorities` | Filtered list of critical and high-risk blocked permits. | Focuses attention on immediate project risks. |
| `portfolio://daily-action-plan` | Role-assigned tasks for coordinators, engineers, expediters. | Enforces daily operational alignment. |
| `portfolio://systemic-bottlenecks` | Cross-project root causes (insurance lapses, missing PE stamps). | Diagnoses systemic portfolio risks. |
| `portfolio://changes` | Day-over-day status transitions and new examiner comments. | Provides instant overnight delta awareness. |

### Prompts (4 Standardized Workflows)

- `daily_standup_briefing`: Generates full morning meeting briefing with health metrics and action items.
- `triage_permit_blockers`: Parameterized deep-dive to unblock a specific stuck permit (`permit_id`).
- `plan_resubmission_strategy`: Formulates point-by-point technical defense for city plan-check rejections (`permit_id`).
- `audit_contractor_compliance`: Regulatory audit for contractor ROC license and insurance standing (`contractor_id`).

Why Prompts: Standardizes prompt engineering so any team member gets consistent, senior-grade output with one click.

---

## 4. How to Run It

### Setup
```bash
git clone https://github.com/rohitbagal1819/PermitFlow-MCP.git
cd PermitFlow-MCP
uv venv
uv sync
```

### Run Server
- Local STDIO (Claude / Cursor): `uv run permitflow-mcp`
- Networked HTTP / SSE: `uv run permitflow-mcp --transport sse --port 8000`

### Client Config
- Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "permitflow-mcp": {
      "command": "uv",
      "args": ["--directory", "d:\\PermitFlow-MCP", "run", "permitflow-mcp"]
    }
  }
}
```
- Cursor IDE (Settings > Features > MCP): Add Command `uv --directory "d:\PermitFlow-MCP" run permitflow-mcp`

---

## 5. Host Comparison: What Differed Across Hosts

| Dimension | Claude Desktop | Cursor IDE |
| :--- | :--- | :--- |
| Primary Strength | Executive standup reasoning, multi-tool chaining, and document drafting. | Technical engineering workflows and blueprint code integration. |
| Tool Invocation | Interactive UI confirmation prompts before executing tools. | Direct agent loop execution during coding/editing sessions. |
| Resources & Prompts | Full native UI support (`portfolio://` attachments and slash prompts). | Tools supported directly; resources queried via programmatic tool calls. |
| Model Behavior | Claude 3.5 Sonnet handles complex nested schemas and auto-chains tools. | Requires explicit, concise tool descriptions to prevent parameter guessing. |

---

## 6. Workflow: Where It Fits in the Company's Process

Pre-Construction Permitting Pipeline:
1. Intake: Ingests subcontractor SOW, detects trades, checks PE structural stamp triggers (`intake_project_scope`).
2. Budget & SLA: Projects city fees and review timelines (`estimate_permit_fees_and_sla`).
3. Pre-Flight Gate: Audits package readiness (0-100 GO / NO-GO) and checks contractor $1M insurance (`check_permit_readiness`, `verify_contractor_registration`).
4. City Submittal: Permit Coordinator files verified packet with city portal (Phoenix ProjectDox, Tempe Accela).
5. Comment Resolution: If city examiners reject, system queries municipal RAG and auto-generates PE-sealed transmittal letter (`generate_formal_ahj_response_packet`).
6. Human-in-the-Loop Sign-Off: Professional Engineer (PE) and Permit Coordinator must review and seal before final filing.

Local vs. Team: STDIO mode runs locally on workstations with zero latency. HTTP/SSE mode supports centralized team deployment across cloud workers.

---

## 7. Space: Token Counts Before vs. After

| Approach | Context Load | Latency | Result |
| :--- | :--- | :--- | :--- |
| Raw Document Dumping (Full Code Corpus) | ~28,450 tokens | High | Context bloat, hallucination risk |
| PermitFlow In-Memory BM25 RAG | ~1,450 tokens | Sub-5ms | Grounded legal citations (PMC 301.5, IBC 1609) |
| Net Efficiency | **94.9% Token Reduction** | **95% Faster** | **Zero hallucinations** |

Chunking Details: 500 words per chunk, 60-word overlap, 3.5x section-title weight boosting, returning top 3-5 governing sections.

---

## 8. Screenshots and Demo Video

- Demo Video: https://drive.google.com/file/d/1Q7kjDj28XWBAHAi5OtZCaVF3Ypx0wF-U/view?usp=sharing
- Shareable URL: `https://drive.google.com/file/d/1j3tYW5fvyOfwpIauRr-qK2_kpjZn-UBb/view?usp=sharing`
- Verification: 100% test pass rate across 7 tools, 5 resources, 4 prompts, and file persistence.