# mcp-server 天气服务

本项目包含基于 Model Context Protocol (MCP) 的天气查询服务，分别用 Go 和 Python 实现，支持通过 MCP 工具获取指定城市的实时天气，适用于 AI 助手、自动化脚本等场景。

---

## 目录结构

```
src/
  weather-go/      # Go 版本实现
  weather-python/  # Python 版本实现
```

---

## 功能特性
- 查询任意城市的实时天气
- 支持 MCP 协议，易于集成
- 提供 Go 与 Python 两种实现

---

## 依赖环境

### Go 版本
- Go 1.24.5 及以上
- 依赖见 `src/weather-go/go.mod`

### Python 版本
- Python 3.13 及以上
- 依赖见 `src/weather-python/pyproject.toml`

---

## 安装与运行

### Go 版本
1. 进入目录：
   ```bash
   cd src/weather-go
   ```
2. 配置环境变量（需先获取和风天气 API Key，见下文）：
   ```bash
   export QWEATHER_API_KEY="你的key"
   export QWEATHER_API_HOST="https://xxx.re.qweatherapi.com"
   ```
3. 启动服务：
   - 方式A：
     ```bash
     go run main.go
     ```
   - 方式B（推荐）：
     ```bash
     go build -o weather_service main.go
     ./weather_service
     ```
   或使用 `start.sh` 脚本。

### Python 版本
1. 进入目录：
   ```bash
   cd src/weather-python
   ```
2. 安装依赖：
   ```bash
   pip install .
   ```
3. 配置环境变量（需先获取和风天气 API Key，见下文）：
   ```bash
   export QWEATHER_API_KEY="你的key"
   export QWEATHER_API_HOST="https://xxx.re.qweatherapi.com"
   ```
4. 启动服务：
   ```bash
   python -m pangerl_mcp_server_weather.server
   # 或
   python main.py
   ```

---

## 获取和风天气 API Key

1. 访问和风天气开发者平台：[https://dev.qweather.com/docs/api/weather/weather-now](https://dev.qweather.com/docs/api/weather/weather-now)
2. 注册并登录账号。
3. 创建项目并获取你的 API Key。
4. 在服务配置或环境变量中填写你的 API Key。

详细开发配置和 API 使用说明请参考和风天气官方文档：[和风天气开发文档](https://dev.qweather.com/docs/)。

---

## MCP 配置示例

以 Python 版本为例，在 Cursor、Claude Code 或其他支持 MCP 的客户端中，添加如下配置到 `.cursor/mcp.json` 或全局 MCP 配置文件：

```json
{
  "mcpServers": {
    "weather": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "pangerl_mcp_server_weather.server"
      ],
      "env": {
        "QWEATHER_API_KEY": "xxx",
        "QWEATHER_API_HOST": "https://xxx.re.qweatherapi.com"
      }
    }
  }
}
```

Go 版本只需将 `command` 和 `args` 替换为 Go 可执行文件路径及参数。

---

## 工具参数说明

### Python 版本
- `get_current_weather`
  - `city` (string, 必填): 城市名称。例如："beijing"、"上海"。

### Go 版本
- `get_forecast`
  - `location` (string, 必填): 查询的地理位置（如城市名称、LocationID 或经纬度，推荐城市名）。

---

## 开发与贡献

欢迎提交 issue 和 PR 进行功能完善与 bug 修复。

---

## 参考资料
- [和风天气开发文档](https://dev.qweather.com/docs/)
- [Model Context Protocol (MCP)](https://github.com/mark3labs/mcp)
- [README 编写指南](https://github.com/Tinymrsb/READMEhowto)
- [GitHub 官方 README 说明](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)