# 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: [项目地址]