许可数据MCP服务器
一个全面的FastMCP服务器，为布伦瑞克县NC许可证系统提供14个JSON模式驱动的工具，用于许可证数据管理、联系人丰富、分析和报告生成。
🚀 特性
核心能力
- 数据新鲜度检查 -验证本地许可证数据是否最新
- 完整和增量数据获取 -下载完整的许可证数据集或最近的更改
- 联系人丰富 -自动附加承包商和业主联系信息
- 管道编排 -组合下载、处理和丰富工作流程
- 高级过滤和分析 -基于日期的筛选、自定义表达式和统计摘要
- 地理编码支持 -将许可证地址转换为坐标
- 分包商管理 -用于跟踪当前分包商的CRUD操作
- 报告生成 -多种输出格式（Markdown、Word、CSV）
- 通信有效载荷 -为利益相关者外联生成模板消息
可用工具
check_permit_data-数据新鲜度验证download_permits-完成许可证数据集下载get_recent_permits-增量数据获取enrich_with_contacts-丰富联系信息run_pipeline-端到端数据处理工作流filter_permits_by_date-日期范围过滤filter_permits-自定义表达式过滤permit_stats_summary-统计分析和分组geocode_permit_addresses-地址地理编码get_current_subcontractors-分包商列表检索update_current_subcontractors-分包商管理get_contacts_for_permit-个人许可证联系人查询generate_contact_payload-通信模板生成generate_reports-创建多格式报告
📋 先决条件
- Python 3.8或更高版本
- 访问布伦瑞克县许可API
- 有效的API端点（在环境中配置）
🛠️ 安装
地方发展
- 克隆存储库:
git clone https://github.com/YOUR_USERNAME/permit-data-mcp-server.git
cd permit-data-mcp-server- 安装依赖项:
pip install -r requirements.txt- 配置环境:
cp .env.example .env
# Edit .env with your specific configuration- 运行服务器:
python permit_mcp_server.pyDocker部署
- 使用Docker Compose （推荐）：
docker-compose up -d- 直接使用Docker:
docker build -t permit-mcp-server .
docker run -p 8000:8000 --env-file .env permit-mcp-server⚙️ 配置
环境变量
创建一个 .env 文件基于 .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_hereAPI终点
该服务器与多个不伦瑞克县系统集成：
- ArcGIS功能服务器 -主要许可证数据源
- eTRAKiT项目搜索 -项目查找和验证
- eTRAKiT承包商API -联系人信息检索
📖 使用示例
基础数据提取
# 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"
)联系人丰富
# 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
)过滤和分析
# 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"
)报告生成
# Generate multiple report formats
reports = generate_reports(
df_json=permits_data,
group_label="Q4_2024",
formats=["markdown", "word", "csv"]
)🧪 测试
运行测试套件：
# 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📁 项目结构
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参考
工具类别
数据管理
- check_permit_data -验证数据新鲜度和同步状态
- 下载_权限 -带可选缓存的完整数据集下载
- 获取_中心_许可证 -基于编辑时间戳的增量更新
加工和浓缩
- 丰富人脉 -附上承包商联系信息
- run_pipeline -自动化的端到端处理工作流程
- 地理许可地址 -将地址转换为地理坐标
过滤和分析
- 筛选器_许可证_日期 -基于时间的数据过滤
- 过滤器_许可证 -基于表达式的自定义过滤
- permit_stats_summary -统计分析和分组操作
状态管理
- get_current分包商 -检索跟踪的分包商列表
- update_current_subsectors -在跟踪中添加/删除分包商
沟通与报告
- get_contacts_for_permit -个人许可证联系人查询
- generate_contact_payload -基于模板的消息生成
- 生成报告 -创建多格式报告（MD、Word、CSV）
🚦 健康监测
服务器包括内置的健康检查：
- HTTP端点:
GET /health - Docker健康检查：自动集装箱健康监测
- 日志记录：使用相关ID进行全面的请求跟踪
🤝 贡献
- 分叉存储库
- 创建要素分支：
git checkout -b feature/amazing-feature - 提交您的更改：
git commit -m 'Add amazing feature' - 推到分支：
git push origin feature/amazing-feature - 打开拉取请求
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🆘 支持
对于问题、疑问或贡献：
- 检查现有
- 创建具有详细描述的新问题
- 包括日志和配置详细信息（已清理）
🔗 相关项目
- FastMCP框架 -底层MCP服务器框架
- 布伦瑞克县地理信息系统 -数据源文档
______________________________________________________________________
使用FastMCP构建 | 支持MCP协议 | 生产就绪