npm package: @jellohung/weather-mcp-server
Description: A simple weather query MCP server with weather forecast and clothing suggestions
Author: jello
Latest version: 1.0.1

# Weather MCP Server 使用指南

一个基于 TypeScript 开发的天气查询 MCP (Model Context Protocol) 服务，提供城市天气查询、天气预报和穿衣建议功能。

## 目录

- [功能介绍](#功能介绍)
- [安装部署](#安装部署)
- [客户端配置](#客户端配置)
- [使用示例](#使用示例)
- [开发说明](#开发说明)

## 功能介绍

本服务提供以下三个工具：

### 1. get_weather - 天气查询

获取指定城市的实时天气信息，包括：
- 温度
- 天气状况（晴/阴/雨等）
- 湿度
- 风力
- AQI 空气质量指数

### 2. get_weather_forecast - 天气预报

获取指定城市未来 1-7 天的天气预报。

### 3. get_clothing_suggestion - 穿衣建议

根据当前天气情况，给出穿衣搭配建议。

### 支持的城市

| 城市 | 中文 | 英文 |
|------|------|------|
| 北京 | 北京 | beijing |
| 上海 | 上海 | shanghai |
| 广州 | 广州 | guangzhou |
| 深圳 | 深圳 | shenzhen |
| 杭州 | 杭州 | hangzhou |
| 成都 | 成都 | chengdu |

## 安装部署

### 环境要求

- Node.js >= 18.0.0
- npm 或 yarn

### 安装步骤

```bash
# 进入项目目录
cd /Users/jello/Documents/mcp/test-mcp

# 安装依赖
npm install

# 编译 TypeScript
npm run build
```

编译完成后，会在 `dist/` 目录生成可执行的 JavaScript 文件。

### 验证安装

```bash
# 运行测试
npx tsx test.ts
```

## 客户端配置

### Trae IDE 配置

1. 打开 Trae 设置，找到 MCP 配置文件位置
2. 添加以下配置：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/jello/Documents/mcp/test-mcp/dist/index.js"]
    }
  }
}
```

### Cursor IDE 配置

1. 打开 Cursor 设置 (`Cmd + ,`)
2. 搜索 "MCP" 或找到 MCP 配置项
3. 添加服务器配置：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/jello/Documents/mcp/test-mcp/dist/index.js"]
    }
  }
}
```

### Claude Desktop 配置

编辑 Claude Desktop 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加配置：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/jello/Documents/mcp/test-mcp/dist/index.js"]
    }
  }
}
```

### Windsurf 配置

在 Windsurf 设置中添加 MCP 服务器：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/jello/Documents/mcp/test-mcp/dist/index.js"]
    }
  }
}
```

## 使用示例

配置完成后，重启 IDE 或 MCP 客户端，即可在对话中使用。

### 示例 1：查询天气

```
用户：北京今天天气怎么样？

AI：🌤️ 北京天气预报

📅 更新时间: 2024-03-13 10:00:00
🌡️ 温度: 15°C
🌤️ 天气: 晴
💧 湿度: 45%
🌬️ 风力: 北风3级
📊 AQI指数: 42

✅ 空气质量优，适合户外活动
```

### 示例 2：天气预报

```
用户：上海未来三天天气如何？

AI：📅 上海天气预报 (未来3天)

📆 3-13 周五
   🌡️ 18°C | 晴 | 北风3级

📆 3-14 周六
   🌡️ 18°C | 晴 | 东风1级

📆 3-15 周日
   🌡️ 15°C | 雨 | 南风2级

注意：以上预报为模拟数据，仅供学习参考
```

### 示例 3：穿衣建议

```
用户：广州今天穿什么衣服合适？

AI：👔 广州穿衣建议

🌡️ 当前温度: 24°C
🌤️ 当前天气: 阴

💡 建议: 舒适，建议穿长袖或短袖
```

### 示例 4：英文城市名

```
用户：What's the weather in shenzhen?

AI：🌤️ 深圳天气预报

📅 更新时间: 2024-03-13 10:00:00
🌡️ 温度: 25°C
🌤️ 天气: 晴
💧 湿度: 72%
🌬️ 风力: 南风3级
📊 AQI指数: 45

✅ 空气质量优，适合户外活动
```

## 开发说明

### 项目结构

```
test-mcp/
├── src/
│   └── index.ts        # MCP 服务源代码
├── dist/
│   ├── index.js        # 编译后的 JS 文件
│   └── index.d.ts      # TypeScript 声明文件
├── test.ts             # 测试脚本
├── package.json        # 项目配置
├── tsconfig.json       # TypeScript 配置
└── mcp-config.json     # MCP 配置示例
```

### 开发命令

```bash
# 开发模式运行
npm run dev

# 编译
npm run build

# 生产模式运行
npm start
```

### 扩展开发

如需添加新城市或功能，编辑 `src/index.ts`：

```typescript
const weatherData: Record<string, any> = {
  // 添加新城市数据
  newcity: {
    city: "新城",
    temperature: 20,
    weather: "晴",
    humidity: 60,
    wind: "东风2级",
    aqi: 50,
    updateTime: "2024-03-13 10:00:00",
  },
};

// 添加城市映射
function normalizeCity(city: string): string {
  const cityMap: Record<string, string> = {
    // ...
    newcity: "newcity",
    新城: "newcity",
  };
  // ...
}
```

### 调试方法

使用 MCP Inspector 进行调试：

```bash
npx @modelcontextprotocol/inspector node /Users/jello/Documents/mcp/test-mcp/dist/index.js
```

这会启动一个 Web 界面，可以查看所有 MCP 消息交互。

## 常见问题

### Q: 配置后不生效？

1. 确保路径是绝对路径
2. 确保已运行 `npm run build` 编译项目
3. 重启 IDE 或 MCP 客户端

### Q: 如何添加更多城市？

编辑 `src/index.ts` 中的 `weatherData` 对象和 `normalizeCity` 函数，然后重新编译。

### Q: 如何接入真实天气 API？

可以将 `weatherData` 替换为真实的 API 调用，例如：

```typescript
async function fetchWeather(city: string) {
  const response = await fetch(`https://api.weather.com/${city}`);
  return response.json();
}
```

## 技术栈

- **运行时**: Node.js
- **语言**: TypeScript
- **MCP SDK**: @modelcontextprotocol/sdk
- **参数验证**: Zod

## 许可证

MIT