geoapify-mcp-server

# Geoapify MCP Server 一个基于Geoapify API的MCP (Model Context Protocol) 服务器，提供地理编码、路线规划、地点搜索等位置服务。 ## 功能特性 - 🗺️ **地理编码**: 地址转坐标，坐标转地址 - 🚗 **路线规划**: 多种交通方式的路线计算 - 📍 **地点搜索**: 按类别搜索POI和兴趣点 - 🔍 **地址自动补全**: 实时地址建议 - 📊 **等时线分析**: 可达性区域计算 - 🏢 **地点详情**: 获取详细的地点信息 - 💾 **智能缓存**: Redis/内存缓存支持 - 🔒 **安全认证**: API密钥和IP白名单 - 📝 **完整日志**: 结构化日志记录 - 🐳 **容器化**: Docker和Docker Compose支持 ## 快速开始 ### 1. 获取Geoapify API密钥 1. 访问 [Geoapify官网](https://www.geoapify.com/) 2. 注册账户并创建项目 3. 获取API密钥（免费计划每天3000次调用） ### 2. 本地开发 ```bash # 克隆项目 git clone <repository-url> cd geoapify-mcp-server # 安装依赖 npm install # 配置环境变量 cp .env.example .env # 编辑.env文件，填入你的Geoapify API密钥 # 启动开发服务器 npm run dev ``` ### 3. Docker部署 ```bash # 构建镜像 docker build -t geoapify-mcp . # 运行容器 docker run -p 50001:50001 --env-file .env geoapify-mcp ``` ### 4. Docker Compose部署 ```bash # 启动完整服务栈（包含Redis和Nginx） docker-compose up -d ``` ## 环境变量配置 ```bash # 必需配置 GEOAPIFY_API_KEY=your_geoapify_api_key_here # 可选配置 PORT=50001 NODE_ENV=development MCP_API_KEY=your_mcp_server_api_key_here REDIS_URL=redis://localhost:6379 LOG_LEVEL=info RATE_LIMIT_MAX=100 ALLOWED_ORIGINS=* ALLOWED_IPS=* ``` ## API端点 ### 健康检查 ``` GET /health ``` ### 获取工具列表 ``` GET /tools ``` ### MCP工具调用 ``` POST /tools/{toolName} Content-Type: application/json X-API-Key: your_mcp_api_key { "arguments": { // 工具参数 } } ``` ### 直接API调用 #### 地理编码 ``` POST /geocode { "address": "北京市朝阳区", "options": { "country": "cn", "language": "zh" } } ``` #### 反向地理编码 ``` POST /reverse-geocode { "lat": 39.9042, "lon": 116.4074, "options": { "language": "zh" } } ``` #### 路线规划 ``` POST /routing { "waypoints": ["39.9042,116.4074", "31.2304,121.4737"], "mode": "drive", "options": { "type": "balanced", "details": "instruction_details" } } ``` #### 地点搜索 ``` POST /places { "categories": "catering.restaurant", "filter": "circle:116.4074,39.9042,1000", "options": { "limit": 20, "language": "zh" } } ``` ## 支持的MCP工具 1. **geocode_address** - 地址地理编码 2. **reverse_geocode** - 反向地理编码 3. **calculate_route** - 路线计算 4. **search_places** - 地点搜索 5. **address_autocomplete** - 地址自动补全 6. **calculate_isoline** - 等时线计算 7. **get_place_details** - 地点详情 ## 部署选项 ### 1. 云服务部署 #### Heroku ```bash # 安装Heroku CLI heroku create your-app-name heroku config:set GEOAPIFY_API_KEY=your_key git push heroku main ``` #### AWS Lambda 使用Serverless Framework或AWS SAM部署 #### Google Cloud Run ```bash gcloud run deploy geoapify-mcp \ --source . \ --platform managed \ --region asia-east1 \ --set-env-vars GEOAPIFY_API_KEY=your_key ``` ### 2. VPS部署 ```bash # 使用PM2管理进程 npm install -g pm2 pm2 start src/server.js --name geoapify-mcp pm2 startup pm2 save ``` ### 3. Kubernetes部署参考 `k8s/` 目录中的配置文件 ## 性能优化 - **缓存策略**: 地理编码结果缓存1小时，路线缓存30分钟 - **速率限制**: 默认每15分钟100次请求 - **连接池**: 复用HTTP连接 - **压缩**: 启用gzip压缩 - **日志轮转**: 自动日志文件管理 ## 监控和日志 - 日志文件位置: `logs/` - 健康检查: `GET /health` - 错误追踪: 结构化错误日志 - 性能指标: 请求时间和成功率 ## 安全考虑 - API密钥验证 - IP白名单支持 - 速率限制 - HTTPS强制（生产环境） - 输入验证和清理 - 安全头设置 ## 故障排除 ### 常见问题 1. **API密钥错误** - 检查 `.env` 文件中的 `GEOAPIFY_API_KEY` - 确认密钥有效且未过期 2. **Redis连接失败** - 检查Redis服务是否运行 - 验证连接配置 3. **速率限制** - 检查Geoapify账户配额 - 调整本地速率限制设置 ### 日志查看 ```bash # 查看实时日志 tail -f logs/combined.log # 查看错误日志 tail -f logs/error.log # Docker日志 docker logs geoapify-mcp-server ``` ## 开发指南 ### 添加新工具 1. 在 `src/handlers/mcpHandler.js` 中定义工具 2. 在 `src/services/geoapifyService.js` 中实现API调用 3. 添加输入验证和错误处理 4. 更新文档 ### 测试 ```bash # 运行测试 npm test # 测试覆盖率 npm run test:coverage ``` ## 许可证 MIT License ## 贡献欢迎提交Issue和Pull Request！ ## 支持如有问题，请联系： - 邮箱: your-email@example.com - GitHub Issues: [项目地址]