# 🔗 MCP 集成指南

## 什么是 MCP？

MCP (Model Context Protocol) 是一个标准协议，允许AI模型通过工具调用访问外部服务。通过MCP，您可以在Claude Desktop、其他AI客户端中直接使用Geoapify地理位置服务。

## 🚀 快速配置

### 1. MCP客户端配置

将以下配置添加到您的MCP客户端配置文件中：

```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "npx",
      "args": [
        "-y",
        "geoapify-mcp-server"
      ],
      "env": {
        "GEOAPIFY_API_KEY": "3234bd7e35264a8aa29fc15e89f8f76f"
      }
    }
  }
}
```

### 2. Claude Desktop 配置

对于Claude Desktop，配置文件位置：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### 3. 其他MCP客户端

对于其他支持MCP的客户端，请参考其文档将上述配置添加到相应的配置文件中。

## 🛠️ 可用工具

配置完成后，您将在MCP客户端中获得以下地理位置工具：

### 1. geocode_address
**功能**: 地址地理编码
**用途**: 将地址转换为经纬度坐标

**示例提示**:
```
请帮我查找"北京市天安门广场"的经纬度坐标
```

### 2. reverse_geocode
**功能**: 反向地理编码
**用途**: 将坐标转换为地址

**示例提示**:
```
请告诉我坐标 39.9042, 116.4074 对应的地址
```

### 3. calculate_route
**功能**: 路线规划
**用途**: 计算两点或多点间的最优路线

**示例提示**:
```
请帮我规划从北京到上海的驾车路线
```

### 4. search_places
**功能**: 地点搜索
**用途**: 搜索指定类别的地点

**示例提示**:
```
请帮我找到天安门广场周围1公里内的餐厅
```

### 5. address_autocomplete
**功能**: 地址自动补全
**用途**: 提供地址输入建议

**示例提示**:
```
请帮我补全地址"北京市朝阳"
```

### 6. calculate_isoline
**功能**: 等时线计算
**用途**: 计算可达性区域

**示例提示**:
```
请计算从天安门广场开车30分钟能到达的区域
```

## 📝 使用示例

### 示例1: 旅行规划
```
我想去上海旅行，请帮我：
1. 查找上海外滩的精确坐标
2. 搜索外滩周围2公里内的酒店
3. 规划从浦东机场到外滩的路线
```

### 示例2: 商业分析
```
我想在北京开一家咖啡店，请帮我：
1. 分析三里屯周围1公里内现有的咖啡店分布
2. 计算从三里屯地铁站步行10分钟能覆盖的区域
```

### 示例3: 物流规划
```
我需要规划配送路线，请帮我：
1. 将这些地址转换为坐标：[地址列表]
2. 规划最优的配送路线
3. 计算从仓库出发1小时车程内的配送范围
```

## 🔧 高级配置

### 自定义API密钥
如果您有自己的Geoapify API密钥，可以替换配置中的密钥：

```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "npx",
      "args": ["-y", "geoapify-mcp-server"],
      "env": {
        "GEOAPIFY_API_KEY": "your_custom_api_key_here"
      }
    }
  }
}
```

### 多个服务实例
您可以配置多个实例，使用不同的API密钥或配置：

```json
{
  "mcpServers": {
    "geoapify-maps-primary": {
      "command": "npx",
      "args": ["-y", "geoapify-mcp-server"],
      "env": {
        "GEOAPIFY_API_KEY": "primary_api_key"
      }
    },
    "geoapify-maps-backup": {
      "command": "npx",
      "args": ["-y", "geoapify-mcp-server"],
      "env": {
        "GEOAPIFY_API_KEY": "backup_api_key"
      }
    }
  }
}
```

### 环境变量配置
您也可以通过环境变量配置：

```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "npx",
      "args": ["-y", "geoapify-mcp-server"],
      "env": {
        "GEOAPIFY_API_KEY": "${GEOAPIFY_API_KEY}",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

## 🧪 测试配置

### 1. 验证配置
重启您的MCP客户端后，应该能看到Geoapify工具出现在可用工具列表中。

### 2. 测试基本功能
尝试以下简单测试：

```
请帮我查找"纽约时代广场"的坐标
```

### 3. 测试复杂功能
尝试更复杂的查询：

```
请帮我规划从洛杉矶国际机场到好莱坞星光大道的路线，并找到沿途的加油站
```

## 🔍 故障排除

### 常见问题

#### 1. 工具未出现
- 检查配置文件格式是否正确
- 确认MCP客户端已重启
- 查看客户端日志是否有错误信息

#### 2. API调用失败
- 验证API密钥是否有效
- 检查网络连接
- 确认API配额是否充足

#### 3. 响应缓慢
- 检查网络连接质量
- 考虑使用更近的API端点
- 减少请求的数据量

### 调试方法

#### 1. 启用详细日志
```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "npx",
      "args": ["-y", "geoapify-mcp-server"],
      "env": {
        "GEOAPIFY_API_KEY": "your_api_key",
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```

#### 2. 手动测试
您可以直接测试MCP服务器：

```bash
# 启动MCP服务器
npx geoapify-mcp-server

# 发送测试消息
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx geoapify-mcp-server
```

## 📚 更多资源

- **Geoapify API文档**: https://docs.geoapify.com/
- **MCP协议规范**: https://modelcontextprotocol.io/
- **Claude Desktop文档**: https://claude.ai/desktop
- **项目GitHub**: [您的项目链接]

## 💡 使用技巧

1. **组合使用工具**: 可以在一个对话中组合使用多个地理位置工具
2. **具体描述需求**: 提供详细的地址和要求，获得更准确的结果
3. **利用缓存**: 相同的查询会被缓存，提高响应速度
4. **批量处理**: 可以一次处理多个地址或位置

---

🎉 **配置完成！现在您可以在MCP客户端中享受强大的地理位置服务了！**