内容
# MCP 天气服务器学习项目
## 贡献者
由 munir.ai.eng@gmail.com 构建的学习项目，用于搭建 MCP 服务器。
MCP 协议的实践介绍。本仓库包含一个天气 MCP 服务器、示例客户端和基于 Docker 的 SSE 部署。
它是在学习 MCP 主机、客户端、服务器、工具、资源和提示如何协同工作时构建的。
## 什么是 MCP？
MCP 是一种标准方法，允许 AI 应用程序发现并使用外部功能。MCP 服务器提供一致的接口，兼容主机可以连接到该接口，而不是为每个 AI 应用程序构建单独的集成。
```text
MCP 主机（Cursor / Claude Desktop / 自定义应用程序）
|
v
MCP 客户端
|
v
MCP 服务器
|
v
Weather.gov API
```
- **主机**：AI 应用程序，例如 Cursor 或 Claude Desktop。
- **客户端**：管理 MCP 会话并调用服务器功能的连接层。
- **服务器**：提供工具、资源和提示的程序。
- **工具**：AI 可以调用的操作。此项目提供天气警报和预报。
- **资源**：通过 URI 暴露的数据，例如配置或回声示例。
- **提示**：可重用的提示模板，例如包含的代码审查提示。
## 仓库布局
```text
mcp_v1/
|-- server/
| |-- weather.py # 本地 FastMCP 天气服务器（stdio）
| `-- example.py # 小型示例服务器
|-- client/
| |-- weather.json # MCP 客户端配置
| `-- weather.py # 交互式 MCP + LLM 客户端
`-- mcp_docker/
|-- server.py # SSE 天气服务器
|-- client-sse.py # 连接到 SSE 服务器
|-- client-stdio.py # 通过 stdio 连接
`-- Dockerfile # 容器镜像定义
```
## 功能
- `get_alerts(state)` 检索美国两个字母的州代码的活跃天气警报。
- `get_forecast(latitude, longitude)` 检索美国某个位置的短期预报（Docker/SSE 服务器）。
- 使用 `httpx.AsyncClient` 调用 [国家气象局 API](https://www.weather.gov/documentation/services-web-api)。
- 演示 **stdio** 和 **SSE** 传输。
- 包括示例 MCP 资源和可重用提示。
## 先决条件
- Python 3.11+（本地项目当前声明 Python 3.14+）
- [uv](https://docs.astral.sh/uv/)
- Docker Desktop（仅适用于 Docker 示例）
- 可选：Cursor 或 Claude Desktop，从 AI 主机使用服务器
- 可选：用于 `client/weather.py` 的 Groq API 密钥
## 运行本地 MCP 服务器
从项目目录开始：
```powershell
cd mcp_v1
uv sync
uv run mcp run server/weather.py
```
服务器使用 **stdio** 传输，旨在由 MCP 主机启动和管理，而不是在浏览器中打开。
## 连接到 MCP 主机
示例配置在 [`mcp_v1/client/weather.json`](mcp_v1/client/weather.json) 中。更新两个 Windows 路径以匹配您的克隆和虚拟环境：
```json
{
"mcpServers": {
"weather": {
"command": "C:\\path\\to\\mcp_v1\\.venv\\Scripts\\mcp.exe",
"args": [
"run",
"C:\\path\\to\\mcp_v1\\server\\weather.py"
]
}
}
}
```
在主机应用程序的 MCP 配置中添加等效的服务器条目，然后重启主机。主机可以发现 `get_alerts` 工具，并使用诸如 `CA` 或 `NY` 的值调用它。
## 运行 Docker / SSE 示例
```powershell
cd mcp_v1/mcp_docker
docker build -t mcp-weather-server .
docker run --rm -p 8000:8000 mcp-weather-server
```
在第二个终端中，为客户端安装依赖项并运行：
```powershell
cd mcp_v1/mcp_docker
uv run client-sse.py
```
客户端连接到 `http://localhost:8000/sse`，列出可用工具，然后请求加利福尼亚州的警报。
通过 stdio 在 Docker 中测试相同的服务器程序：
```powershell
cd mcp_v1/mcp_docker
uv run client-stdio.py
```
## 可选 LLM 客户端
`mcp_v1/client/weather.py` 是使用 `mcp-use` 和 Groq 的交互式聊天客户端。在 `mcp_v1/client` 中创建一个 `.env` 文件：
```env
GROQ_API_KEY=your_api_key
GROQ_MODEL=openai/gpt-oss-20b
```
然后运行：
```powershell
cd mcp_v1
uv run client/weather.py
```
## 注意
- 天气 API 涵盖美国国家气象局数据，因此使用美国州代码和坐标。
- API 请求包括用户代理头和基本错误处理。
- 永远不要提交 `.env` 文件或 API 密钥。
## 学习成果
该项目演示：
- MCP 主机、客户端和服务器职责
- 使用 FastMCP 注册工具、资源和提示
- 使用 `httpx` 异步调用外部 HTTP API
- 使用 stdio 进行本地主机集成
- 在 Docker 中运行 MCP 服务器的 SSE
- 将 AI/LLM 客户端连接到 MCP 工具
## 许可证
这是一个个人学习项目。在公开分发或重用之前，请添加许可证文件。
