OSM地理JSON数据处理服务器

Name: OSM地理JSON数据处理服务器
Author: shimizu

作者：shimizu5 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

技术文档摘要

OSM GeoJSON MCP 服务器

这是一个通过 Overpass API 获取 OpenStreetMap 数据并以 GeoJSON 格式存储的 MCP (Model Context Protocol) 服务器。

🌟 主要功能

🗺️ 地理数据获取工具 (8种)

🏢 建筑物数据获取 (get_buildings): 获取住宅、商业、工业和公共建筑的数据
🛣️ 道路网络获取 (get_roads): 获取从高速公路到住宅区道路的所有道路数据
🏪 设施数据获取 (get_amenities): 获取餐厅、医院、学校等 POI 数据
🌊 水域数据获取 (get_waterways): 获取河流、湖泊、运河、水库等水域数据
🌳 绿地数据获取 (get_green_spaces): 获取公园、森林、农田、草地等绿地数据
🚃 铁路数据获取 (get_railways): 获取铁路线路、车站、地铁、有轨电车等数据

🔧 系统功能（4种）

📊 API 统计 (get_api_stats): 监控使用统计、缓存状态和错误率
🔧 连接测试 (test_connection): 对 Overpass API 服务器进行连接诊断
🔄 数据转换 (convert_to_geojson): 将 OSM 数据转换为 GeoJSON
📁 下载功能: 提供3种数据下载工具
📁 文件输出: 所有工具均支持文件导出功能 (.geojson/.json)

🚀 高级功能

💾 缓存系统

15分钟TTL: 符合 OSM 规则的缓存期限
LRU算法: 高效的内存缓存管理
重复请求预防: 自动使用同一查询的缓存结果

📈 日志与监控功能

详细日志: 跟踪 API 使用情况、响应时间及错误率
统计信息: 缓存命中率、服务器性能
实时监控: 显示运行时间和请求频率

⚡ 错误处理

MCP标准错误: 通过 McpError 类实现标准错误代码
多服务器支持: 自动切换至3个备用服务器
指数退避: 在速率限制时适应性等待
5xx系列错误处理: 自动重试服务器错误
详细错误信息: 提供有助于调试的附加信息

📦 安装与使用方法

1. 安装依赖项

npm install

2. 启动服务器

# 正常启动
npm start

# 开发模式（使用 MCP Inspector）
npm run dev

3. 运行测试

# 运行所有测试
npm test

# 运行关键测试
npm run test:critical

# 快速测试（关键测试 + 早期终止）
npm run test:fast

# 单独测试运行
npm run test:simple       # 基本连接测试
npm run test:diagnostic   # 网络诊断
npm run test:features     # 新功能测试
npm run test:download     # 下载功能测试
npm run test:direct       # 直接文件输出测试

# MCP协议验证测试（新功能）
node test/mcp-protocol-verification.js    # 验证协议合规性
node test/error-handling-test.js          # 验证错误处理
node test/integration-test.js             # 运行集成测试

🎯 在 Claude 中的使用示例

💬 提示词示例

📍 获取特定区域的建筑物数据

请获取东京站周边（东经139.765-139.768度，北纬35.679-35.682度）的建筑物数据，并以 GeoJSON 格式返回。

🏙️ 收集用于区域分析的数据

请收集新宿站周边以下数据并保存到文件中：
- 商业设施的建筑物数据
- 主要道路的道路网络
- 餐饮店
坐标范围为东经139.695-139.705度，北纬35.685-35.695度。

🔢 有限数量的数据获取

请获取涩谷站周边最多30个建筑物的数据，并仅限于商业设施，以 GeoJSON 格式输出。

📊 系统状况确认

请检查 OSM 服务器的连接状态和 API 使用统计。

🌊 河流与水域调查

请获取皇居周边（东经139.75-139.77度，北纬35.68-35.69度）的水域数据（包括河流、沟渠等）。

🚀 快速数据获取

请快速获取品川站周边最多10个铁路数据，并尽量缩短响应时间。

🗺️ 地图数据应用示例

1. 城市规划与房地产分析

希望获取涩谷站周边500米四方的建筑物、道路和公园数据，以便分析城市密度。

→ 可以分析建筑物密度、道路可达性和绿地比例等

2. 旅游路线创建

希望获取浅草寺周边最多50个旅游景点（包括餐馆、神社、公园）的数据，以及步行道路的数据。

→ 可以为游客创建步行路线或景点地图

3. 灾难疏散计划

希望收集学校周边可用于疏散的道路、公园和公共设施的数据，重点关注20个重要的设施。

→ 可用于优化疏散路线和疏散地点

4. 交通基础设施调查

希望使用品川站周边的铁路、道路和公交站数据来分析交通可达性，重点关注主要交通工具15个。

→ 可用于评估交通便利性和城市规划

📄 响应格式

GeoJSON 响应（标准）

{
  "type": "geojson",
  "data": {
    "type": "FeatureCollection",
    "features": [...]
  },
  "summary": {
    "feature_count": 42,
    "limit_applied": 50,
    "is_truncated": false,
    "bbox": [139.765, 35.679, 139.768, 35.682],
    "building_type": "all"
  }
}

文件输出响应

{
  "status": "success",
  "message": "已下载建筑物数据",
  "file": "./data/tokyo_buildings.geojson",
  "size": "0.85 MB",
  "feature_count": 245,
  "limit_applied": null,
  "is_truncated": false,
  "building_type": "all",
  "bbox": [139.765,  35.679, 139.768, 35.682],
  "server": "overpass-api.de"
}

API 统计响应

{
  "timestamp": "2025-07-07T13:00:00.000Z",
  "api_statistics": {
    "uptime": { "formatted": "2h 30m" },
    "requests": { "total": 150, "perMinute": "1.2" },
    "cache": { "hitRate": "75.3%" },
    "errors": { "errorRate": "0.7%" }
  },
  "cache_statistics": { "size": 45 },
  "compliance_info": {
    "user_agent": "OSM-MCP/1.0",
    "rate_limiting": "enabled",
    "caching": "enabled (15min TTL)",
    "overpass_api_compliance": "full"
  }
}

🛠️ 可用工具详情（共12个工具）

🏢 get_buildings

获取建筑物数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
building_type (可选): 建筑类型 (residential, commercial, industrial, public, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径（.geojson/.json）

🛣️ get_roads

获取道路网络数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
road_types (可选): 道路类型数组 (motorway, trunk, primary, secondary, tertiary, residential, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径

🏪 get_amenities

获取设施数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
amenity_type (可选): 设施类型 (restaurant, hospital, school, bank, cafe, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径

🌊 get_waterways

获取水域数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
waterway_type (可选): 水域类型 (river, stream, canal, lake, reservoir, pond, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径

🌳 get_green_spaces

获取绿地数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
green_space_type (可选): 绿地类型 (park, forest, garden, farmland, grass, meadow, nature_reserve, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径

🚃 get_railways

获取铁路数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
railway_type (可选): 铁路类型 (rail, subway, tram, monorail, station, platform, all)
limit (可选): 获取的最大数量（1-10000）
output_path (可选): 文件输出路径

📊 get_api_stats

获取 API 使用统计和系统状态。

参数:

reset (可选): 是否重置统计（布尔值）

🔧 test_connection

测试与 Overpass API 服务器的连接。

参数: 无

🔄 convert_to_geojson

将 OSM 文件转换为 GeoJSON。

参数:

input_path: 输入 OSM 文件路径（必须）
output_path: 输出 GeoJSON 文件路径（必须）

📁 download_osm_data

下载原始 OSM 数据。

参数:

query: Overpass QL 查询（必须）
output_path: 保存文件路径（必须）
format (可选): 输出格式 (json, xml)

🌐 download_area_all

下载指定区域的所有数据。

参数:

minLon, minLat, maxLon, maxLat: 获取范围的坐标（必须）
output_path: 保存文件路径（必须）

🔬 技术细节

MCP 协议实现

符合 JSON-RPC 2.0: 完整的协议实现
标准错误代码: 通过 McpError 类实现适当的错误处理
初始化处理器: 支持 InitializedNotificationSchema
利用 MCP SDK: 最大限度地利用 SDK 功能，减少自定义实现

OSM/Overpass API 规则遵守

用户代理识别: 通过 OSM-MCP/1.0 进行适当识别
遵守速率限制: 采用指数退避和服务器负载均衡
缓存实现: 通过 15 分钟 TTL 防止重复请求
内存限制: 通过 1GB 内存限制减轻服务器负载
超时优化: 180 秒超时符合 Overpass API 推荐值

高性能架构

多服务器故障转移: 自动切换至3个备用服务器
直接 IP 连接: 使用直接 IP 地址避免 DNS 问题
异步处理: 使用 Node.js 标准 https/fs 模块实现高效通信
流处理: 直接写入大容量数据文件

数据质量保证

OSM 到 GeoJSON 转换: 通过自定义转换逻辑实现高精度转换
几何处理: 正确生成 Point/LineString/Polygon 形状
坐标验证: 严格检查边界框和 WGS84 坐标系
元数据保留: 完整保留 OSM 标签并转换为 GeoJSON 属性

监控与调试功能

实时统计: 跟踪请求次数、响应时间和错误率
缓存分析: 分析命中率、内存使用量和 TTL 管理
服务器监控: 检查每个 Overpass API 服务器的健康状况
全面测试: 自动执行连接、功能和性能测试

🏆 MCP 协议兼容性

✅ 完全兼容（2025年7月更新）

📋 MCP 2024-11-05 规范: 完全兼容
🔧 错误处理: 通过 McpError 类实现标准错误代码
🧪 测试质量: 协议、错误和集成测试 100% 成功率
🚀 Claude Code 集成: 确认稳定运行

📊 实现细节

功能类别	兼容性	详情
初始化处理器	✅ 完成	支持 `initialize`, `initialized`
协议响应	✅ 完成	符合 JSON-RPC 2.0
工具功能	✅ 完成	12个工具，已验证模式
错误处理	✅ 完成	标准错误代码 (-32601, -32602, -32603)
集成测试	✅ 完成	已验证实用场景

🧪 质量保证

协议测试: 5/5 成功（ping, initialize, initialized, tools/list, tools/call）
错误处理测试: 5/5 成功（参数验证、坐标验证、未知工具等）
集成测试: 9/9 成功（实际数据获取、并行处理、所有工具运行验证）
性能测试: 支持并行处理，缓存功能正常运行

⚠️ 限制事项与建议

边界框大小

推荐大小: 0.005° × 0.005° 以下（约500米四方）
最大大小: 0.001平方度以下（防止超时）
城市区域: 建议在较小范围内分割获取

性能考虑

建筑物查询: 比道路查询成本更高
关系处理: 边界线数据复杂度较高
缓存利用: 同一范围内的重复获取将在15分钟内被缓存

遵守使用条款

速率限制: 建议每秒不超过1次请求
适当用途: 适用于教育、研究和非营利目的
减轻服务器负载: 积极利用缓存功能

📈 性能指标

实测值（东京站周边 0.003° × 0.003°）

建筑物数据: 20条记录，4.4秒，22KB
道路数据: 361条记录，2.1秒，129KB
设施数据: 24条记录，12.6秒，4.5KB
缓存命中: < 1秒（加速75%）

🔢 数量限制功能

自然语言中的数量限制

提示中包含“最多30条”、“10条左右”、“5条以内”等表达时，会自动应用数量限制：

请获取东京站周边最多50条建筑物数据
↓ 自动应用 limit: 50

请获取品川站周边10条左右的铁路数据
↓ 自动应用 limit: 10

OSM地理JSON数据处理服务器

项目介绍

技术文档摘要

OSM GeoJSON MCP 服务器

🌟 主要功能

🗺️ 地理数据获取工具 (8种)

🔧 系统功能（4种）

🚀 高级功能

💾 缓存系统

📈 日志与监控功能

⚡ 错误处理

📦 安装与使用方法

1. 安装依赖项

2. 启动服务器

3. 运行测试

🎯 在 Claude 中的使用示例

💬 提示词示例

📍 获取特定区域的建筑物数据

🏙️ 收集用于区域分析的数据

🔢 有限数量的数据获取

📊 系统状况确认

🌊 河流与水域调查

🚀 快速数据获取

🗺️ 地图数据应用示例

1. 城市规划与房地产分析

2. 旅游路线创建

3. 灾难疏散计划

4. 交通基础设施调查

📄 响应格式

GeoJSON 响应（标准）

文件输出响应

API 统计响应

🛠️ 可用工具详情（共12个工具）

🏢 get_buildings

🛣️ get_roads

🏪 get_amenities

🌊 get_waterways

🌳 get_green_spaces

🚃 get_railways

📊 get_api_stats

🔧 test_connection

🔄 convert_to_geojson

📁 download_osm_data

🌐 download_area_all

🔬 技术细节

MCP 协议实现

OSM/Overpass API 规则遵守

高性能架构

数据质量保证

监控与调试功能

🏆 MCP 协议兼容性

✅ 完全兼容（2025年7月更新）

📊 实现细节

🧪 质量保证

⚠️ 限制事项与建议

边界框大小

性能考虑

遵守使用条款

📈 性能指标

实测值（东京站周边 0.003° × 0.003°）

🔢 数量限制功能

自然语言中的数量限制

支持的表达模式

数量限制规格

🎛️ Claude Code 设置