# Weather MCP Server

一个基于 Model Context Protocol (MCP) 的天气服务器，支持获取全球城市的实时天气信息。

## 🌟 功能特性

- **实时天气查询** - 获取全球任意城市的当前天气信息
- **多语言支持** - 支持中英文城市名称查询
- **优雅降级** - 无API密钥时自动提供演示数据
- **完整气象数据** - 温度、湿度、风速、气压、天气状况
- **免费API支持** - 集成OpenWeather免费API（每分钟60次调用）

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置API密钥（可选）

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑.env文件，添加您的OpenWeather API密钥
OPENWEATHER_API_KEY=your_actual_api_key_here
```

> 💡 **提示**: 访问 [OpenWeatherMap](https://openweathermap.org/api) 注册获取免费API密钥

### 3. 构建项目

```bash
npm run build
```

### 4. 运行服务器

```bash
# 生产模式
npm start

# 开发模式（自动构建并运行）
npm run dev
```

## 📋 使用方法

### 作为独立MCP服务器运行

服务器启动后通过stdio进行JSON-RPC通信：

```bash
node dist/index.js
```

### 集成到Claude Desktop

在Claude Desktop配置文件 (`claude_desktop_config.json`) 中添加：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp-server/dist/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 集成到CodeBuddy Code

在CodeBuddy Code的MCP配置中添加：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp-server/dist/index.js"]
    }
  }
}
```

## 🔧 可用工具

### `get_current_weather`

获取指定城市的当前详细天气信息。

**请求参数:**
```typescript
{
  city: string  // 城市名称（支持中英文）
}
```

**返回数据:**
```typescript
{
  location: string     // 城市位置信息
  temperature: number  // 温度（摄氏度）
  description: string  // 天气描述
  humidity: number     // 湿度百分比
  windSpeed: number   // 风速（公里/小时）
  pressure: number    // 气压（百帕）
}
```

## 🎯 使用示例

### 示例1: 查询北京天气

```
用户: 北京今天天气怎么样？
助手: [调用 get_current_weather 工具，city="北京"]

🌤️ 当前北京天气：
📍 位置: 北京, CN
🌡️ 温度: 22°C
☁️ 天气: 部分多云
💧 湿度: 65%
💨 风速: 15 km/h
📊 气压: 1013 hPa
```

### 示例2: 查询纽约天气

```
用户: What's the weather in New York?
助手: [调用 get_current_weather 工具，city="New York"]

🌤️ Current weather in New York:
📍 Location: New York, US
🌡️ Temperature: 18°C  
☁️ Conditions: clear sky
💧 Humidity: 55%
💨 Wind Speed: 12 km/h
📊 Pressure: 1015 hPa
```

## 🛠️ 开发命令

```bash
# 安装依赖
npm install

# 构建TypeScript项目
npm run build

# 开发模式（监听变化并自动构建）
npm run dev

# 运行测试
node test-mcp.js
```

## 📁 项目结构

```
weather-mcp-server/
├── src/
│   ├── index.ts      # MCP服务器主入口
│   └── weather.ts    # 天气服务核心逻辑
├── dist/             # 编译后的JavaScript文件
├── .env              # 环境变量配置文件
├── .env.example      # 环境变量模板
├── package.json      # 项目配置和依赖
└── README.md         # 项目说明文档
```

## ⚠️ 注意事项

1. **API限制**: OpenWeather免费账户每分钟最多60次API调用
2. **演示模式**: 未设置API密钥时使用静态演示数据
3. **城市格式**: 支持中文和英文城市名称
4. **错误处理**: API调用失败时自动降级到演示数据
5. **单位系统**: 使用公制单位（摄氏度、公里/小时）

## 🔗 相关链接

- [Model Context Protocol 官方文档](https://modelcontextprotocol.io)
- [OpenWeatherMap API 文档](https://openweathermap.org/api)
- [Claude Desktop MCP 配置指南](https://docs.anthropic.com/claude/docs/mcp)

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件