Geoapify MCP Server

一个基于Geoapify API的MCP (Model Context Protocol) 服务器，提供地理编码、路线规划、地点搜索等位置服务。

功能特性

• 🗺️ 地理编码: 地址转坐标，坐标转地址
• 🚗 路线规划: 多种交通方式的路线计算
• 📍 地点搜索: 按类别搜索POI和兴趣点
• 🔍 地址自动补全: 实时地址建议
• 📊 等时线分析: 可达性区域计算
• 🏢 地点详情: 获取详细的地点信息
• 💾 智能缓存: Redis/内存缓存支持
• 🔒 安全认证: API密钥和IP白名单
• 📝 完整日志: 结构化日志记录
• 🐳 容器化: Docker和Docker Compose支持

快速开始

1. 获取Geoapify API密钥

1. 访问 Geoapify官网
2. 注册账户并创建项目
3. 获取API密钥（免费计划每天3000次调用）

2. 本地开发

# 克隆项目
git clone <repository-url>
cd geoapify-mcp-server

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑.env文件，填入你的Geoapify API密钥

# 启动开发服务器
npm run dev

3. Docker部署

# 构建镜像
docker build -t geoapify-mcp .

# 运行容器
docker run -p 50001:50001 --env-file .env geoapify-mcp

4. Docker Compose部署

# 启动完整服务栈（包含Redis和Nginx）
docker-compose up -d

环境变量配置

# 必需配置
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

# 安装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

gcloud run deploy geoapify-mcp \
  --source . \
  --platform managed \
  --region asia-east1 \
  --set-env-vars GEOAPIFY_API_KEY=your_key

2. VPS部署

# 使用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账户配额
   • 调整本地速率限制设置

日志查看

# 查看实时日志
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. 更新文档

测试

# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

支持

如有问题，请联系：

• 邮箱: [email protected]
• GitHub Issues: [项目地址]