Permit Data MCP Server Nhc

PermitData FastMCP服务器-新汉诺威县（NHC）

一个全面的FastMCP服务器，通过ArcGIS Feature Services集成提供8个专门的工具来管理新汉诺威县的建筑许可证数据。

🚀 快速开始

# 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

服务器将在以下时间启动 http://localhost:8000/mcp

📋 特性

数据管理

• check_permit_data：验证数据新鲜度，并比较本地与服务器记录
• 下载_权限：通过智能缓存和分页获取所有许可证
• 获取_中心_许可证：根据日期标准检索许可证

分析和过滤

• 过滤器_许可证：应用Python表达式过滤许可数据集
• permit_stats_summary：生成按指定字段分组的统计摘要

状态管理

• get_current分包商：检索缓存的分包商列表
• update_current_subsectors：从持久状态添加/删除分包商

报告

• 生成报告：创建带有时间戳输出的markdown和CSV报告

🛠 配置

环境变量

创建一个 .env 文件来自 .env.example 并配置：

# 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

所需依赖关系

• fastmcp >=0.1.0：FastMCP框架
• 熊猫 >=2.0.0：数据操作和分析
• 请求： >=2.31.0:API调用的HTTP客户端
• python-文件工具 >=2.8.2：日期解析工具
• python dotenv >=1.0.0：环境变量管理

🐳 Docker部署

使用Docker Compose（推荐）

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

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

直接使用Docker

# 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参考

工具：check_permit_data

验证数据新鲜度和同步状态。

参数：

• base_url （str）：ArcGIS功能服务URL
• local_csv （str）：用于比较的本地CSV文件的路径
• delta_days （int，默认值=1）：过期检查的天数阈值
• strict （bool，default=False）：在出现错误时引发异常

退货：

{
  "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"
}

工具：下载_权限

通过智能缓存和分页获取所有许可证。

参数：

• base_url （str）：ArcGIS功能服务URL
• force （bool，default=False）：即使缓存是新的，也强制下载
• where （str，default=“1=1”）：用于筛选的SQL WHERE子句
• page_size （int，默认值=10000）：每个API请求的记录
• out_csv （str，可选）：输出缓存的CSV路径

退货：

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

工具：get_recent_permits

根据日期标准检索许可证。

参数：

• base_url （str）：ArcGIS功能服务URL
• since （str）：ISO日期字符串（必填）
• date_field （str，默认值=“ISSUE_DATE”）：要筛选的日期字段
• page_size （int，默认值=10000）：每个API请求的记录

工具：filter_permits

应用Python表达式过滤许可数据集。

参数：

• permits_json （列表\[Dict\]）：允许记录过滤
• filter_expr （str）：Python表达式（例如，“row\['PERMIT_VALUE\]>50000”）

工具：permit_stats_summary

生成按指定字段分组的统计摘要。

参数：

• permits_json （列表\[Dict\]）：允许分析记录
• group_by （str，default=“GENERAL_CONTRACTOR”）：用于分组的字段

🧪 测试

使用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

📁 项目结构

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

🔧 发展

地方发展设置

# 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

数据源信息

此服务器连接到新汉诺威县的公共ArcGIS Feature Service：

• 服务URL: https://gis.nhcgov.com/server/rest/services/Thematic/BuildingPermits/FeatureServer/0
• 数据类型：新汉诺威县颁发的建筑许可证
• 更新频率：实时（在处理许可证时）
• 地区范围：北卡罗来纳州新汉诺威县

注：与不伦瑞克县不同，新汉诺威县不会公开EnerGov/COAST公共端点以获取承包商联系信息。

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

• 问题：通过以下方式报告错误或请求功能
• 文档：FastMCP文档位于https://github.com/jlowin/fastmcp
• 数据源：新汉诺威县地理信息系统门户

🔗 相关项目

• 不伦瑞克县许可MCP服务器 -原始模板
• FastMCP框架 -基础MCP框架

______________________________________________________________________

内置于❤️ 使用 FastMCP 新汉诺威县许可证数据管理。