高德地址解析服务

基于Claude AI和高德地图MCP的智能地址解析服务，提供强大的地址解析、地理编码和位置信息查询功能。

🚀 功能特性

• 智能地址解析: 使用Claude AI理解自然语言地址查询
• 高德地图集成: 通过MCP协议集成高德地图API
• 多种查询方式: 支持地址转坐标、坐标转地址、POI搜索等
• 多轮工具调用: 支持复杂的多轮次工具调用，完成连续任务
• 多种LLM支持: 支持Claude和OpenAI等大模型
• RESTful API: 提供完整的HTTP API接口
• 异步处理: 高性能异步架构，支持并发请求
• 健康监控: 完善的健康检查和监控机制
• 错误处理: 完善的异常处理和错误恢复机制

📋 系统要求

• Python 3.10+
• Node.js 16+ (用于高德MCP服务器)
• 高德地图API密钥
• Claude API密钥

🛠️ 安装配置

1. 克隆项目

git clone <repository-url>
cd address-parser-service

2. 创建Python环境

方式一：使用pip（推荐）

# 创建虚拟环境
python -m venv address-parser-env

# 激活虚拟环境
# Windows:
address-parser-env\Scripts\activate
# macOS/Linux:
source address-parser-env/bin/activate

# 安装依赖
pip install -r requirements.txt

方式二：使用conda

# 方法1: 使用environment.yml文件（推荐）
conda env create -f environment.yml
conda activate address-parser

# 方法2: 手动创建环境
conda create -n address-parser python=3.11
conda activate address-parser

# 安装依赖
pip install -r requirements.txt

# 或者使用conda安装部分依赖
conda install fastapi uvicorn pydantic
pip install mcp anthropic structlog pydantic-settings

3. 配置环境变量

复制环境变量模板：

cp .env.example .env

编辑 .env 文件，填入你的API密钥：

# Claude API配置
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 高德地图API配置  
AMAP_MAPS_API_KEY=your_amap_api_key_here

# 其他配置保持默认即可

4. 获取API密钥

高德地图API密钥

1. 访问 高德开放平台
2. 注册账号并创建应用
3. 获取Web服务API密钥

Claude API密钥

1. 访问 Anthropic Console
2. 创建账号并获取API密钥

🚀 快速开始

方式一：使用示例脚本

# 激活环境（如果使用虚拟环境）
# pip环境:
source address-parser-env/bin/activate  # macOS/Linux
# 或
address-parser-env\Scripts\activate     # Windows

# conda环境:
conda activate address-parser

# 运行基础使用示例
python examples/basic_usage.py

方式二：启动API服务

# 启动FastAPI服务
python api/main.py

服务启动后访问：

• API文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/api/v1/health

方式三：直接使用MCP客户端

import asyncio
from src.mcp_client import AmapMCPClient, ClaudeHandler

async def main():
    # 创建MCP客户端
    async with AmapMCPClient() as amap_client:
        # 创建Claude处理器
        claude_handler = ClaudeHandler(amap_client)
        
        # 处理查询
        result = await claude_handler.process_query(
            "请帮我解析这个地址：北京市朝阳区三里屯太古里"
        )
        
        print(result["final_answer"])

asyncio.run(main())

📖 API文档

地址解析接口

POST /api/v1/address/parse

请求体：

{
    "address": "北京市朝阳区三里屯太古里",
    "context": {
        "city": "北京",
        "preferences": "详细地址信息"
    },
    "system_prompt": "请提供详细的地址解析结果"
}

响应：

{
    "success": true,
    "request_id": "1642123456789_abc12345",
    "data": {
        "formatted_address": "北京市朝阳区三里屯太古里",
        "location": "116.397428,39.90923",
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区"
    },
    "response": "根据您提供的地址，我已经成功解析出详细信息...",
    "tool_calls": [...],
    "processing_time": 2.5
}

健康检查接口

GET /api/v1/health

响应：

{
    "status": "healthy",
    "mcp_connected": true,
    "claude_available": true,
    "tools_count": 5,
    "uptime": 3600.0
}

工具列表接口

GET /api/v1/tools

响应：

{
    "success": true,
    "tools": [
        {
            "name": "geocode",
            "description": "地理编码，将地址转换为坐标",
            "input_schema": {...}
        }
    ],
    "count": 1
}

🔧 高级配置

MCP服务器管理

使用内置的服务器管理脚本：

# 启动高德MCP服务器
python scripts/start_amap_server.py start

# 停止服务器
python scripts/start_amap_server.py stop

# 重启服务器
python scripts/start_amap_server.py restart

# 查看状态
python scripts/start_amap_server.py status

# 监控模式（自动重启）
python scripts/start_amap_server.py monitor

配置参数说明

参数	默认值	说明
LLM_PROVIDER	claude	大语言模型提供商（claude或openai）
ANTHROPIC_API_KEY	必填	Claude API密钥
CLAUDE_MODEL	claude-3-7-sonnet-20250219	Claude模型版本
CLAUDE_MAX_TOKENS	1000	Claude最大输出token数量
ENABLE_TOKEN_EFFICIENT_TOOLS	false	是否启用Claude token高效工具调用
TOOL_MAX_ITERATIONS	10	工具调用最大迭代次数
OPENAI_API_KEY	可选	OpenAI API密钥
OPENAI_MODEL	gpt-4	OpenAI模型版本
OPENAI_MAX_TOKENS	1000	OpenAI最大输出token数量
MCP_SERVER_TIMEOUT	30	MCP服务器超时时间（秒）
MCP_RETRY_COUNT	3	重试次数
MCP_RETRY_DELAY	1.0	重试延迟（秒）
LOG_LEVEL	INFO	日志级别
API_HOST	127.0.0.1	API服务主机
API_PORT	8000	API服务端口

🧪 测试

运行单元测试

# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_mcp_client.py -v

# 运行集成测试（需要API密钥）
pytest tests/ -m integration

# 运行多轮工具调用测试
python tests/run_tests.py --claude    # 仅运行Claude测试
python tests/run_tests.py --openai    # 仅运行OpenAI测试
python tests/run_tests.py --complex   # 仅运行复杂多轮测试
python tests/run_tests.py --all       # 运行所有测试

测试覆盖率

# 生成测试覆盖率报告
pytest --cov=src tests/

📁 项目结构

address-parser-service/
├── src/                    # 核心源代码
│   ├── mcp_client/        # MCP客户端模块
│   │   ├── amap_client.py # 高德MCP客户端
│   │   ├── claude_handler.py # Claude处理器
│   │   └── openai_handler.py # OpenAI处理器
│   ├── core/              # 核心模块
│   │   ├── config.py      # 配置管理
│   │   ├── logger.py      # 日志配置
│   │   └── exceptions.py  # 异常定义
│   └── utils/             # 工具函数
│       └── helpers.py     # 辅助函数
├── api/                   # API服务模块
│   ├── main.py           # FastAPI主应用
│   ├── routes/           # API路由
│   └── schemas/          # 数据模型
├── tests/                # 测试代码
│   ├── test_mcp_client.py # MCP客户端测试
│   ├── test_multi_tool_calls.py # 多轮工具调用测试
│   ├── test_complex_multi_tool_calls.py # 复杂多轮工具调用测试
│   └── test_openai_multi_tool_calls.py # OpenAI多轮工具调用测试
├── scripts/              # 脚本文件
├── examples/             # 使用示例
├── logs/                 # 日志文件
├── requirements.txt      # Python依赖
├── .env.example         # 环境变量模板
└── README.md            # 项目文档

🔍 使用示例

基础地址解析

# 地址转坐标
query = "北京市朝阳区三里屯太古里"
result = await claude_handler.process_query(query)

# 坐标转地址
query = "116.397428,39.90923 这个坐标对应的地址是什么？"
result = await claude_handler.process_query(query)

# POI搜索
query = "帮我查找北京大学的地理坐标"
result = await claude_handler.process_query(query)

多轮工具调用示例

# 多轮次工具调用示例 - 天气比较
query = "查询一下北京市和上海市今天的天气，并告诉我在这两个城市中，哪个城市更适合户外活动？"
result = await claude_handler.process_query(query)

# 复杂多轮工具调用 - 旅行规划
query = """请帮我规划一次从北京到上海的旅行路线：
1. 首先查询北京和上海的天气情况
2. 然后查询北京市区到上海市区的驾车路线
3. 再查询途经城市杭州市的著名景点
4. 最后给我一个综合考虑天气和路线的详细旅行计划建议
"""
result = await claude_handler.process_query(query)

批量处理

curl -X POST "http://localhost:8000/api/v1/address/batch" \
     -H "Content-Type: application/json" \
     -d '[
       {"address": "北京市朝阳区三里屯"},
       {"address": "上海市浦东新区陆家嘴"},
       {"address": "广州市天河区珠江新城"}
     ]'

🐛 故障排除

常见问题

1. MCP连接失败

   • 检查 AMAP_MAPS_API_KEY 是否正确设置
   • 确认网络连接正常
   • 查看日志文件获取详细错误信息

2. Claude API调用失败

   • 检查 ANTHROPIC_API_KEY 是否正确设置
   • 确认API密钥有足够的配额
   • 检查网络连接

3. 工具调用超时

   • 增加 MCP_SERVER_TIMEOUT 配置值
   • 检查高德地图API服务状态

4. 依赖包冲突

   • 使用虚拟环境隔离依赖：python -m venv address-parser-env
   • 或使用conda环境：conda create -n address-parser python=3.11
   • 清理pip缓存：pip cache purge

5. conda环境问题

   • 确保激活了正确的环境：conda activate address-parser
   • 如果遇到依赖冲突，尝试混合安装：

     conda install fastapi uvicorn pydantic
     pip install mcp anthropic structlog pydantic-settings
     

日志查看

# 查看应用日志
tail -f logs/app.log

# 查看API访问日志
tail -f logs/api.log

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Anthropic - Claude AI API
• 高德地图 - 地图服务API
• Model Context Protocol - MCP协议
• FastAPI - Web框架

📞 支持

如果你遇到问题或有建议，请：

1. 查看 FAQ
2. 搜索现有的 Issues
3. 创建新的 Issue

---

注意: 本项目仅供学习和研究使用，请遵守相关API服务的使用条款。