Map Server MCP

丹妮·查因-202107582

EECE798S-作业5

配备OpenAI代理SDK的MCP地图服务器

使用OpenAI代理SDK实现三个模型上下文协议（MCP）服务器，提供地图、旅行分析和天气/环境服务。

______________________________________________________________________

🎯 项目概述

该项目实施 三台MCP服务器 随着 总共11次操作 作为代理工具：

______________________________________________________________________

🚀 快速开始

1.安装（3分钟）

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate          # macOS/Linux
venv\Scripts\activate              # Windows

# Install dependencies
pip install -r requirements.txt

# Configure OpenAI API key
cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-your-key-here

注： 设置 verbose 参数在 agent.py 将“True”设置为“True”，以便打印代理在应答前进行的工具调用。

2.运行项目

交互式代理（带示例查询）：

python agent.py

运行测试：

pytest tests/ -v

______________________________________________________________________

🎯 MCP架构

此实现遵循模型上下文协议约定：

1. 服务器参数 -每台服务器的配置
2. 异步操作 -所有I/O都是非阻塞的
3. 结构化响应 -一致性 {success, ...} 格式
4. 工具定义 -OpenAI函数调用模式
5. 资源管理 -适当清理 close()

刀具流

User Query
    ↓
OpenAI Agent (decides which tools to use)
    ↓
Tool Execution (agent_tools.py routes to server)
    ↓
MCP Server Method (performs operation)
    ↓
External API Call
    ↓
Structured Response
    ↓
Agent Formats Response for User

______________________________________________________________________

📚 服务器详细信息

核心地图服务器(servers/core_map_server.py)

使用OpenStreetMap API进行实时映射。

操作：

• geocode(query) -从地址获取坐标
• reverse_geocode(lat, lon) -从坐标中获取地址
• search_poi(lat, lon, radius, category, key) -查找附近的地点
• get_place_details(place_id) -详细的地点信息
• get_route(origin_lat, origin_lon, dest_lat, dest_lon, mode) -计算路线

外部API： 提名、OSRM、天桥

历史地图服务器(servers/history_map_server.py)

使用历史旅行数据进行旅行模式分析。

操作：

• get_frequent_places(start_date, end_date, min_visits) -访问量最大的地点
• summarize_travel_stats(start_date, end_date) -旅行统计汇总
• get_typical_route(origin_label, dest_label, time_of_day) -路线模式

数据： 使用中发现的100个生成的行程 data/trip_history.json

天气与环境服务器(servers/weather_environment_server.py)

任何地点的天气和环境数据。

操作：

• get_current_weather(lat, lon, include_forecast) -温度、条件、风
• get_air_quality(lat, lon) -空气质量指数、污染物、健康建议
• get_astronomy_data(lat, lon, date) -日出、日落、月相

外部API： 开放天气

______________________________________________________________________

💡 示例用法

python agent.py

💬 You: What's the weather in Paris?
🤖 Agent: [Uses geocode + get_current_weather tools]

💬 You: Find coffee shops near Times Square
🤖 Agent: [Uses geocode + search_poi tools]

💬 You: How's the air quality in Beijing?
🤖 Agent: [Uses geocode + get_air_quality tools]

💬 You: Route from Central Park to Brooklyn Bridge by walking
🤖 Agent: [Uses geocode + get_route tools]

💬 You: What are my travel statistics?
🤖 Agent: [Uses summarize_travel_stats tool]

______________________________________________________________________

🗂️ 项目结构

mcp-map-servers/
├── agent.py                         # Main interactive agent
├── agent_tools.py                   # Tool definitions & routing
├── agent_prompt.txt                 # The agent prompt
├── servers/
│   ├── core_map_server.py           # Geocoding, POI, routing
│   ├── history_map_server.py        # Travel pattern analysis
│   └── weather_map_server.py        # Weather & environment
├── tests/
│   └── test_servers.py              # Unit tests
├── data/
│   └── trip_history.json            # Generated data
├── requirements.txt
├── .env.example
└── README.md                        # This file
└── REFLECTION.md                    # Lessons learned and potential next steps
└── SUMMARY.md                       # Summary of the huggingface MCP article and existing map servers
└── Screencast.mp4                   # Video showcasing examples and explaining implementation

______________________________________________________________________

🧪 测试

运行所有测试：

pytest tests/ -v

运行特定测试：

pytest tests/test_servers.py::TestCoreMapServer::test_geocode_success -v

测试包括：

• 所有11个服务器操作
• 成功和错误案例
• 真正的API集成
• 数据结构验证

______________________________________________________________________

⚙️ 配置

环境变量(.env)

OPENAI_API_KEY=sk-your-key-here
API_RATE_LIMIT_DELAY=1.0
OPENAI_MODEL="gpt-4o"

服务器参数

每台服务器使用 ServerParams 用于配置的数据类：

@dataclass
class ServerParams:
    name: str = "server_name"
    description: str = "Server description"
    base_url: str = "https://api.example.com"
    rate_limit_delay: float = float(os.getenv("API_RATE_LIMIT_DELAY"))

______________________________________________________________________

🌐 外部API

所有API都是 自由 和 无需身份验证.

______________________________________________________________________

🔐 错误处理

所有操作都返回一致的结构：

成功：

{
    "success": True,
    "data": "...",
    # ... other fields
}

失败：

{
    "success": False,
    "error": "Descriptive error message"
}

这允许代理人：

1. 检查操作是否成功
2. 适当提取数据或报告错误
3. 优雅地处理失败

______________________________________________________________________

🚧 扩展系统

向现有服务器添加新工具

1. 在中向服务器类添加方法 servers/
2. 将工具定义添加到 TOOLS 在 agent_tools.py
3. 将路由案例添加到 execute_tool() 在 agent_tools.py
4. 可选：在中编写测试 tests/test_servers.py

创建新服务器

1. 创建 servers/new_server.py 随着 ServerParams 服务器类
2. 导入并初始化 agent_tools.py
3. 将工具定义添加到 TOOLS 列表
4. 将路由案例添加到 execute_tool()
5. 更新系统提示 agent.py
6. 可选：编写测试

______________________________________________________________________

任务交付成果

1. SUMMARY.md（拥抱面MCP文章和现有地图服务器摘要）
2. REFLECTION.md（经验教训和潜在的下一步行动）
3. 演员阵容：

https://github.com/user-attachments/assets/a032c84c-b936-4008-a52b-57ab35f456a4