# 🌤️ Weather MCP Server (Node.js)

基于 **Node.js / Express** 实现的远程 **MCP (Model Context Protocol)** 服务器。
通过 [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 暴露 `get_weather` 工具,让 Claude Code 等 MCP 客户端可以**实时查询任意城市的当前天气**。

天气数据来自 [wttr.in](https://wttr.in) —— **免费、无需注册、无需 API key**。

## ✨ 功能特性

- 🛰️ **远程 MCP 服务**:基于官方 `@modelcontextprotocol/sdk` 实现 Streamable HTTP 传输,支持 JSON 与 SSE 两种响应模式
- 🌆 **全球城市支持**:直接传城市名(如 `Beijing`、`Tokyo`、`Paris`)即可查询当地天气
- 🔌 **完整会话管理**:自动生成/校验 `Mcp-Session-Id`,支持会话的建立、复用与关闭(DELETE)
- 🧩 **单文件即用**:无需数据库,零配置文件,一个 `server.js` 即可启动

## 📦 环境要求

- Node.js ≥ 18(内置 `fetch`,无需额外依赖)

## 🚀 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 启动服务(默认端口 3000)
npm start

# 后台运行(日志写入 logs/server.log)
npm run start:bg
```

启动成功后,服务地址为:

```
http://localhost:3000/mcp
```

### 常用脚本

| 命令 | 说明 |
| --- | --- |
| `npm start` | 前台启动服务 |
| `npm start:bg` | 后台启动,日志写入 `logs/server.log` |
| `npm run dev` | 开发模式,文件变更自动重启 |
| `npm run status` | 查看 3000 端口服务是否在运行 |
| `npm run logs` | 实时查看日志 |
| `npm run stop` | 停止服务 |
| `npm run restart` | 重启服务 |
| `npm run restart:bg` | 后台重启 | 

## 🔌 配置 MCP 客户端

在 Claude Code 或其他支持 Streamable HTTP 的 MCP 客户端中,将服务注册为**远程 MCP 服务器**。

### Claude Code

通过 MCP 服务器列表添加(<kbd>/mcp</kbd> → 添加 → **HTTP**):

```json
{
  "type": "http",
  "url": "http://localhost:3000/mcp"
}
```

### JSON 配置文件方式

```json
{
  "mcpServers": {
    "weather": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

## 🧰 提供的工具

### `get_weather`

获取指定城市的当前天气情况。

**参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `city` | string | ✅ | 城市名称,例如 `Beijing`、`Tokyo` |

**返回示例**

```
当前 Beijing 的天气是晴(Sunny),温度 28°C(体感 30°C),湿度 45%,风速 12 km/h。
```

## ⚙️ 实现说明

- **会话隔离**:每个会话持有独立的 `Server` + `transport` 实例(SDK 的 `connect()` 只支持一个 transport),通过 `Mcp-Session-Id` 请求头关联。
- **新会话流程**:不带 `Mcp-Session-Id` 的 POST 视为初始化请求,服务器生成会话 ID 并通过 `Mcp-Session-Id` 响应头返回(通过 CORS 的 `exposedHeaders` 显式暴露给浏览器客户端)。
- **兼容性处理**:无会话 ID 的 GET SSE 探测请求会保持一个打开的 SSE 流(而非返回 404/400),让 Claude Code 等客户端可以继续走 POST 初始化流程。
- **可靠的错误返回**:天气 API 调用失败时返回 `isError: true` 的结果而非让整个请求崩溃。

## 🗂️ 项目结构

```
.
├── server.js          # 全部服务逻辑(单文件)
├── package.json       # 项目配置与脚本
├── logs/              # 运行时日志(已被 .gitignore 忽略)
└── LICENSE            # MIT 许可证
```

## 📄 License

[MIT](LICENSE)