🌤️ Kaushik's Weather MCP Server

![Tests](https://img.shields.io/badge/Tests-Passing-brightgreen.svg

Готовый к продакшену Model Context Protocol (MCP) сервер, написанный на TypeScript, подключающий LLM (такие как Claude Desktop, Cursor и пользовательские AI-агенты) к метеорологическим данным National Weather Service (NWS / NOAA) в реальном времени.

🔗 Живое доказательство интеграции

🚀 Проверено в работе с Claude Desktop: Посмотрите живую сессию чата, демонстрирующую получение прогноза в реальном времени, оповещения и диагностику здоровья:
👉 Посмотреть живое доказательство Claude AI Chat

Related MCP server: mcp-weather

✨ Архитектурные особенности

• 🏗️ Модульная чистая архитектура: Разделена на выделенные сервисные слои (CacheService, RateLimiterService, NwsClient, Logger, Formatter).

• 📡 Официальные метеорологические бюллетени: Структурированные отчёты о погоде со стандартизированными метаданными и указанием источника.

• ⚡ Кэширование в памяти (TTL 5 минут): Потокобезопасный кэш в памяти, снижающий трафик к вышестоящему API до 80%.

• 🛡️ Уровень безопасности Zero-Vibe: Строгая санитизация входных данных, экранирование XSS-сущностей и изолированное ограничение скорости для клиентов (100 запросов/мин).

• 🔁 Устойчивость и отказоустойчивость: Автоматические повторные попытки с экспоненциальной задержкой для ошибок HTTP 5xx / 429 и защита от тайм-аутов запросов.

• 🩺 Наблюдаемость и диагностика: Встроенные инструменты health_check, get_metrics и clear_cache со структурированным JSON-логированием.

📁 Структура проекта

weather/
├── src/
│   ├── config/          # Central configuration & runtime constants
│   ├── services/        # Core business logic (Cache, RateLimiter, NwsClient, Formatter, Logger)
│   ├── tools/           # MCP Tool handlers (alerts, forecast, diagnostics)
│   ├── types/           # Strongly typed TypeScript interfaces
│   ├── utils/           # Input sanitization and security helpers
│   └── index.ts         # Server bootstrap, transport initialization & graceful shutdown
├── tests/
│   ├── unit/            # Unit test suites (utils, sanitizer, cache)
│   ├── integration/     # Upstream NWS API integration & retry tests
│   ├── performance/     # Cache throughput & rate-limiting load tests
│   ├── security/        # XSS, injection prevention & boundary tests
│   └── basic.test.ts    # Comprehensive test runner
├── build/               # Compiled ES module JavaScript distribution
├── package.json
└── tsconfig.json

🛠️ MCP-инструменты

🚀 Начало работы

1. Клонирование и установка

git clone https://github.com/Kaushik2105/mcp-weather.git
cd mcp-weather
npm install

2. Сборка

npm run build

3. Запуск тестов

npm test

🔌 Подключение к Claude Desktop

Добавьте эту конфигурацию в файл конфигурации Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kaushik-weather": {
      "command": "node",
      "args": [
        "c:/Workholic/LawSikho/POCs/weather/weather/build/index.js"
      ]
    }
  }
}

Примечание: Перезапустите Claude Desktop после сохранения конфигурации.

💬 Примеры запросов для Claude

• "Покажи официальный бюллетень прогноза от погодного инструмента Каушика для Лос-Анджелеса (Lat: 34.0522, Lon: -118.2437)"

• "Есть ли активные предупреждения о погоде для Флориды (FL)?"

• "Запусти диагностику здоровья на погодном MCP-сервере Каушика."

👨💻 Автор

Kaushik Karmakar

• GitHub: @Kaushik2105

• Живое доказательство интеграции: Claude AI Chat