grande-weather-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Weather MCP Server 🌤️
+
+A Model Context Protocol (MCP) server that provides weather data from OpenWeather API. Supports both **STDIO** and **SSE** transport modes.
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+### Features
+
+- 🌡️ **Real-time Weather** - Get current weather for any city
+- 📅 **5-Day Forecast** - Get weather forecast up to 5 days
+- 🌍 **Bilingual Support** - Works with English and Chinese city names
+- 🔌 **Dual Transport** - Supports both STDIO and SSE modes
+- 🔑 **Flexible Auth** - API key via URL, Header, or environment variable
+
+### Installation
+
+#### Option 1: NPX (Recommended for STDIO)
+
+No installation needed! Just configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "weather-mcp-server"],
+      "env": {
+        "OPENWEATHER_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: Global Install
+
+```bash
+npm install -g weather-mcp-server
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "weather-mcp",
+      "env": {
+        "OPENWEATHER_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 3: SSE Mode (Remote Server)
+
+If deployed to a server (e.g., Render, Railway):
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "transport": "sse",
+      "url": "https://your-server.com/sse?key=your_api_key"
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get-weather` | Get real-time weather for a city |
+| `get-forecast` | Get 5-day weather forecast |
+
+### Examples
+
+Ask your AI assistant:
+
+- "What's the weather in Tokyo?"
+- "Get me the 5-day forecast for New York"
+- "北京今天天气怎么样？"
+- "上海未来三天天气预报"
+
+### Self-Hosting (SSE Mode)
+
+```bash
+# Clone the repo
+git clone https://github.com/your-username/weather-mcp-server
+cd weather-mcp-server
+npm install
+
+# Start SSE server
+npm run start:sse
+
+# Or with custom port
+PORT=8080 npm run start:sse
+```
+
+### API Key
+
+Get your free API key from [OpenWeather](https://openweathermap.org/api).
+
+---
+
+## 中文
+
+### 功能特点
+
+- 🌡️ **实时天气** - 获取任意城市的当前天气
+- 📅 **5天预报** - 获取最多5天的天气预报
+- 🌍 **双语支持** - 支持中英文城市名
+- 🔌 **双传输模式** - 同时支持 STDIO 和 SSE 模式
+- 🔑 **灵活认证** - 支持 URL、Header 或环境变量传递 API Key
+
+### 安装使用
+
+#### 方式1: NPX 直接运行（推荐）
+
+无需安装，直接配置 MCP 客户端：
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "weather-mcp-server"],
+      "env": {
+        "OPENWEATHER_API_KEY": "你的API密钥"
+      }
+    }
+  }
+}
+```
+
+#### 方式2: 全局安装
+
+```bash
+npm install -g weather-mcp-server
+```
+
+然后配置：
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "weather-mcp",
+      "env": {
+        "OPENWEATHER_API_KEY": "你的API密钥"
+      }
+    }
+  }
+}
+```
+
+#### 方式3: SSE 远程服务
+
+如果已部署到服务器：
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "transport": "sse",
+      "url": "https://your-server.com/sse?key=你的API密钥"
+    }
+  }
+}
+```
+
+### 可用工具
+
+| 工具 | 描述 |
+|------|------|
+| `get-weather` | 获取城市实时天气 |
+| `get-forecast` | 获取5天天气预报 |
+
+### 使用示例
+
+向 AI 助手提问：
+
+- "东京现在天气怎么样？"
+- "帮我查一下纽约未来5天的天气"
+- "北京今天热不热？"
+- "深圳明天会下雨吗？"
+
+### 获取 API Key
+
+前往 [OpenWeather](https://openweathermap.org/api) 免费注册获取。
+
+---
+
+## License
+
+MIT © Grande350

package/bin/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * Weather MCP Server CLI
+ * 
+ * Usage:
+ *   weather-mcp          # STDIO mode (default)
+ *   weather-mcp stdio    # STDIO mode
+ *   weather-mcp sse      # SSE HTTP server mode
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+// 获取命令行参数
+const args = process.argv.slice(2);
+const mode = args[0] || 'stdio';
+
+// 验证模式
+if (!['stdio', 'sse'].includes(mode)) {
+  console.error(`
+╔═══════════════════════════════════════════════════════╗
+║           Weather MCP Server - CLI Help               ║
+╠═══════════════════════════════════════════════════════╣
+║                                                       ║
+║  Usage:                                               ║
+║    weather-mcp [mode]                                 ║
+║                                                       ║
+║  Modes:                                               ║
+║    stdio    STDIO transport (default)                 ║
+║    sse      SSE HTTP server                           ║
+║                                                       ║
+║  Examples:                                            ║
+║    weather-mcp                                        ║
+║    weather-mcp stdio                                  ║
+║    weather-mcp sse                                    ║
+║                                                       ║
+║  Environment Variables:                               ║
+║    OPENWEATHER_API_KEY  Your OpenWeather API key      ║
+║    PORT                 HTTP port for SSE (def: 3000) ║
+║                                                       ║
+╚═══════════════════════════════════════════════════════╝
+  `);
+  process.exit(1);
+}
+
+// 获取 server.js 路径
+const serverPath = path.join(__dirname, '..', 'index.js');
+
+// 如果是 STDIO 模式，直接 require 执行
+if (mode === 'stdio') {
+  // STDIO 模式需要保持 stdin/stdout 干净
+  process.argv = [process.argv[0], serverPath, 'stdio'];
+  require(serverPath);
+} else {
+  // SSE 模式可以 spawn 子进程或直接运行
+  process.argv = [process.argv[0], serverPath, 'sse'];
+  require(serverPath);
+}

package/index.js

@@ -0,0 +1,402 @@
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const {
+  StdioServerTransport,
+} = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  SSEServerTransport,
+} = require("@modelcontextprotocol/sdk/server/sse.js");
+const { z } = require("zod");
+const axios = require("axios");
+const http = require("http");
+const url = require("url");
+
+// ============ 配置 ============
+const DEFAULT_API_KEY =
+  process.env.OPENWEATHER_API_KEY || "";
+const BASE_URL = "https://api.openweathermap.org/data/2.5";
+const GEO_URL = "https://api.openweathermap.org/geo/1.0/direct";
+
+// Session 存储
+const sessions = new Map();
+
+// ============ 创建 MCP Server ============
+function createServer(apiKeyGetter) {
+  const server = new McpServer({
+    name: "weather-mcp-server",
+    version: "2.3.0",
+  });
+
+  // 工具: 获取当前天气
+  server.tool(
+    "get-weather",
+    "Get real-time weather for a city / 获取城市实时天气",
+    { city: z.string().describe("City name, e.g.: Beijing, London / 城市名") },
+    async ({ city }) => {
+      const apiKey = apiKeyGetter();
+      console.error(`[Tool] get-weather | City: ${city}`);
+
+      try {
+        const geoRes = await axios.get(GEO_URL, {
+          params: { q: city, limit: 1, appid: apiKey },
+          timeout: 10000,
+        });
+
+        if (!geoRes.data?.length) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `City not found: "${city}"` }],
+          };
+        }
+
+        const { lat, lon, name, local_names, country } = geoRes.data[0];
+
+        const weatherRes = await axios.get(`${BASE_URL}/weather`, {
+          params: { lat, lon, appid: apiKey, units: "metric", lang: "zh_cn" },
+          timeout: 10000,
+        });
+
+        const d = weatherRes.data;
+        const displayName = local_names?.zh || local_names?.en || name;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  location: { name: displayName, country, lat, lon },
+                  weather: {
+                    description: d.weather[0].description,
+                    temperature: `${d.main.temp}°C`,
+                    feels_like: `${d.main.feels_like}°C`,
+                    humidity: `${d.main.humidity}%`,
+                    wind_speed: `${d.wind.speed} m/s`,
+                  },
+                  summary: `${displayName}: ${d.weather[0].description}, ${d.main.temp}°C`,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        console.error(`[Error] get-weather:`, error.message);
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Query failed: ${error.message}` }],
+        };
+      }
+    }
+  );
+
+  // 工具: 获取天气预报
+  server.tool(
+    "get-forecast",
+    "Get 5-day weather forecast / 获取5天天气预报",
+    {
+      city: z.string().describe("City name / 城市名"),
+      days: z.number().min(1).max(5).default(3).optional(),
+    },
+    async ({ city, days = 3 }) => {
+      const apiKey = apiKeyGetter();
+      console.error(`[Tool] get-forecast | City: ${city} | Days: ${days}`);
+
+      try {
+        const geoRes = await axios.get(GEO_URL, {
+          params: { q: city, limit: 1, appid: apiKey },
+          timeout: 10000,
+        });
+
+        if (!geoRes.data?.length) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `City not found: "${city}"` }],
+          };
+        }
+
+        const { lat, lon, name, local_names, country } = geoRes.data[0];
+
+        const forecastRes = await axios.get(`${BASE_URL}/forecast`, {
+          params: {
+            lat,
+            lon,
+            appid: apiKey,
+            units: "metric",
+            lang: "zh_cn",
+            cnt: days * 8,
+          },
+          timeout: 10000,
+        });
+
+        const displayName = local_names?.zh || name;
+        const dailyForecasts = [];
+        const seenDates = new Set();
+
+        for (const item of forecastRes.data.list) {
+          const date = item.dt_txt.split(" ")[0];
+          if (!seenDates.has(date) && seenDates.size < days) {
+            seenDates.add(date);
+            dailyForecasts.push({
+              date,
+              weather: item.weather[0].description,
+              temp_max: item.main.temp_max,
+              temp_min: item.main.temp_min,
+              humidity: item.main.humidity,
+            });
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  location: { name: displayName, country },
+                  forecast: dailyForecasts,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        console.error(`[Error] get-forecast:`, error.message);
+        return {
+          isError: true,
+          content: [
+            { type: "text", text: `Forecast failed: ${error.message}` },
+          ],
+        };
+      }
+    }
+  );
+
+  return server;
+}
+
+// ============ 辅助函数 ============
+function extractApiKey(req) {
+  const parsedUrl = url.parse(req.url, true);
+  return (
+    req.headers["x-api-key"] ||
+    req.headers["authorization"]?.replace("Bearer ", "") ||
+    parsedUrl.query.key ||
+    null
+  );
+}
+
+function setCorsHeaders(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Authorization, X-API-Key, Mcp-Session-Id"
+  );
+  res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+}
+
+function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+
+// ============ 主启动逻辑 ============
+async function main() {
+  const mode = process.argv[2] || "stdio";
+
+  if (mode === "sse") {
+    // 使用原生 http 模块，避免 Express 中间件问题
+    const server = http.createServer(async (req, res) => {
+      const parsedUrl = url.parse(req.url, true);
+      const pathname = parsedUrl.pathname;
+
+      console.error(`[${new Date().toISOString()}] ${req.method} ${pathname}`);
+
+      // 设置 CORS
+      setCorsHeaders(res);
+
+      // 处理 OPTIONS 预检请求
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // -------- 健康检查 --------
+      if (pathname === "/health" && req.method === "GET") {
+        return sendJson(res, 200, {
+          status: "ok",
+          version: "2.3.0",
+          transport: "SSE (native http)",
+          activeSessions: sessions.size,
+          uptime: process.uptime(),
+        });
+      }
+
+      // -------- 调试端点 --------
+      if (pathname === "/debug" && req.method === "GET") {
+        const sessionsInfo = [];
+        for (const [id, session] of sessions) {
+          sessionsInfo.push({
+            id,
+            apiKeyPrefix: session.apiKey?.substring(0, 6) + "***",
+            createdAt: session.createdAt,
+          });
+        }
+        return sendJson(res, 200, {
+          activeSessions: sessions.size,
+          sessions: sessionsInfo,
+        });
+      }
+
+      // -------- 工具列表 --------
+      if (pathname === "/tools" && req.method === "GET") {
+        return sendJson(res, 200, {
+          tools: ["get-weather", "get-forecast"],
+          usage: "Connect via SSE at /sse",
+        });
+      }
+
+      // -------- API 测试 --------
+      if (pathname === "/test-api" && req.method === "GET") {
+        const apiKey = extractApiKey(req) || DEFAULT_API_KEY;
+        try {
+          const geoRes = await axios.get(GEO_URL, {
+            params: { q: "London", limit: 1, appid: apiKey },
+            timeout: 10000,
+          });
+          return sendJson(res, 200, {
+            status: "ok",
+            keyUsed: apiKey.substring(0, 6) + "***",
+            found: geoRes.data?.length > 0,
+          });
+        } catch (error) {
+          return sendJson(res, 500, {
+            status: "error",
+            error: error.response?.data || error.message,
+          });
+        }
+      }
+
+      // -------- SSE 连接端点 --------
+      if (pathname === "/sse" && req.method === "GET") {
+        const userKey = extractApiKey(req);
+        const effectiveKey = userKey || DEFAULT_API_KEY;
+
+        console.error(
+          `[SSE] New connection | Key: ${effectiveKey.substring(0, 6)}***`
+        );
+
+        // 创建 transport
+        const transport = new SSEServerTransport("/messages", res);
+        const sessionId = transport.sessionId;
+
+        // 创建 server
+        const mcpServer = createServer(() => {
+          return sessions.get(sessionId)?.apiKey || DEFAULT_API_KEY;
+        });
+
+        // 存储 session
+        sessions.set(sessionId, {
+          transport,
+          server: mcpServer,
+          apiKey: effectiveKey,
+          createdAt: new Date(),
+        });
+
+        console.error(`[SSE] Session created: ${sessionId}`);
+
+        // 监听连接关闭
+        res.on("close", () => {
+          sessions.delete(sessionId);
+          console.error(`[SSE] Session closed: ${sessionId}`);
+        });
+
+        // 连接
+        await mcpServer.connect(transport);
+        return;
+      }
+
+      // -------- 消息处理端点 --------
+      if (pathname === "/messages" && req.method === "POST") {
+        const sessionId = parsedUrl.query.sessionId;
+        console.error(`[Messages] POST | sessionId: ${sessionId}`);
+
+        if (!sessionId) {
+          return sendJson(res, 400, { error: "Missing sessionId" });
+        }
+
+        const session = sessions.get(sessionId);
+        if (!session) {
+          console.error(
+            `[Messages] Session not found. Active: ${Array.from(
+              sessions.keys()
+            ).join(", ")}`
+          );
+          return sendJson(res, 404, { error: "Session not found" });
+        }
+
+        try {
+          // 关键：直接传递原始 req, res，不做任何预处理
+          await session.transport.handlePostMessage(req, res);
+        } catch (error) {
+          console.error(`[Messages] Error: ${error.message}`);
+          if (!res.writableEnded) {
+            sendJson(res, 500, { error: error.message });
+          }
+        }
+        return;
+      }
+
+      // -------- 404 --------
+      sendJson(res, 404, { error: "Not found" });
+    });
+
+    // Session 清理定时器
+    setInterval(() => {
+      const now = Date.now();
+      const timeout = 30 * 60 * 1000;
+      for (const [id, session] of sessions) {
+        if (now - session.createdAt.getTime() > timeout) {
+          sessions.delete(id);
+          console.error(`[Cleanup] Expired session: ${id}`);
+        }
+      }
+    }, 5 * 60 * 1000);
+
+    const PORT = process.env.PORT || 3000;
+    server.listen(PORT, () => {
+      console.error(`
+╔═══════════════════════════════════════════════════════╗
+║           Weather MCP Server v2.3.0                   ║
+╠═══════════════════════════════════════════════════════╣
+║  Transport: SSE (native http - no Express)            ║
+║  Port: ${PORT}                                            ║
+╠═══════════════════════════════════════════════════════╣
+║  Endpoints:                                           ║
+║    GET  /health     - Health check                    ║
+║    GET  /debug      - Debug info                      ║
+║    GET  /test-api   - Test API key                    ║
+║    GET  /tools      - List tools                      ║
+║    GET  /sse        - SSE connection                  ║
+║    POST /messages   - Message handler                 ║
+╚═══════════════════════════════════════════════════════╝
+      `);
+    });
+  } else {
+    // STDIO 模式
+    console.error("[STDIO] Starting...");
+    const server = createServer(() => DEFAULT_API_KEY);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[STDIO] Connected");
+  }
+}
+
+main().catch((error) => {
+  console.error("[Fatal]", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "grande-weather-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for OpenWeather API - supports both SSE and STDIO modes / 天气 MCP 服务器",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "start:sse": "node index.js sse",
+    "start:stdio": "node index.js stdio",
+    "test": "echo \"No tests yet\" && exit 0",
+    "prepublishOnly": "echo 'Ready to publish!'"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "weather",
+    "openweather",
+    "context",
+    "server"
+  ],
+  "author": "511456916@qq.com",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/123liu950/weather-mcp"
+  },
+  "homepage": "https://github.com/123liu950/weather-mcp/blob/main/README.md",
+  "bugs": {
+    "url": "https://github.com/123liu950/weather-mcp/issues"
+  },
+  "bin": {
+    "weather-mcp": "./bin/cli.js",
+    "weather-mcp-server": "./bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.13.3",
+    "eventsource": "^4.1.0",
+    "express": "^5.2.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.1"
+  }
+}