{"id":29671280,"url":"https://github.com/kode-rex/clima","last_synced_at":"2025-08-20T12:07:44.676Z","repository":{"id":303498386,"uuid":"1015655137","full_name":"Kode-Rex/clima","owner":"Kode-Rex","description":"A simple National Weather Service MCP server","archived":false,"fork":false,"pushed_at":"2025-07-08T00:39:09.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-08T01:38:01.590Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kode-Rex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T20:50:06.000Z","updated_at":"2025-07-08T00:39:13.000Z","dependencies_parsed_at":"2025-07-08T01:48:59.247Z","dependency_job_id":null,"html_url":"https://github.com/Kode-Rex/clima","commit_stats":null,"previous_names":["kode-rex/clima"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Kode-Rex/clima","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kode-Rex%2Fclima","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kode-Rex%2Fclima/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kode-Rex%2Fclima/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kode-Rex%2Fclima/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kode-Rex","download_url":"https://codeload.github.com/Kode-Rex/clima/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kode-Rex%2Fclima/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266563915,"owners_count":23948689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T20:07:23.618Z","updated_at":"2025-08-20T12:07:44.654Z","avatar_url":"https://github.com/Kode-Rex.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Weather MCP - National Weather Service Edition\n\nA comprehensive Model Context Protocol (MCP) server that provides **completely free** weather data using the National Weather Service API. Built with FastMCP for modern AI assistant integration.\n\n## Features\n\n### Core Weather Features\n- **Zero Cost**: Completely free weather data from the US Government\n- **No API Keys**: No registration or authentication required\n- **FastMCP Integration**: Modern MCP server using FastMCP framework\n- **National Weather Service API**: Reliable, official US government weather data\n- **Real-time Updates**: SSE support for live weather data streams\n- **Weather Alerts**: Free real-time weather alerts and warnings\n- **Comprehensive Coverage**: Current weather, forecasts, and alerts\n- **FastMCP SSE Transport**: Single unified server with SSE transport for API integration\n\n### Development Features\n- **Modern Python**: Built with Python 3.11+ and modern tooling\n- **Type Safety**: Full type hints with MyPy validation\n- **Code Quality**: Automated formatting (Black) and linting (Ruff)\n- **Comprehensive Testing**: 56+ tests with pytest and async support\n- **Docker Support**: Container-ready with docker-compose\n- **CI/CD Pipeline**: GitHub Actions for automated testing and quality checks\n- **Developer Experience**: Makefile with convenient development commands\n- **Modular Architecture**: Clean service layer with individual test files\n\n## Installation\n\n### Quick Start\n\n1. **Clone the repository**:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd clima-mcp\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   pip install -e \".[dev]\"\n   ```\n\n3. **Set up development environment** (optional):\n   ```bash\n   make dev-setup\n   ```\n\n4. **That's it!** No API keys needed - the National Weather Service API is completely free.\n\n### Alternative Installation Methods\n\n#### Using Docker:\n```bash\n# Quick start\ndocker-compose up --build\n\n# Or using Makefile\nmake docker-run\n```\n\n#### Using Makefile (recommended for development):\n```bash\nmake install-dev\nmake dev-setup\n```\n\n## Usage\n\n### Test the API (Recommended First Step)\n\n```bash\nclima-mcp test\n# or\nmake run-test\n```\n\nYou should see:\n```\n✓ Location search successful: 10001, Manhattan\n✓ Current weather: 81.0°F, Clear\n✓ 5-day forecast: 5 days retrieved\n✓ Weather alerts: 1 active alerts\n🎉 All NWS API tests passed!\n```\n\n### FastMCP Server with SSE Transport\n\nRun the unified FastMCP server with SSE transport for API integration:\n\n```bash\nclima-mcp run\n# or\nmake run\n```\n\nThe server starts on `http://localhost:8000` with FastMCP SSE transport, providing 4 weather tools accessible via HTTP/SSE for integration with OpenAI and other AI services.\n\n### Test the Server\n\nOpen the interactive test client:\n```bash\nopen examples/sse_client.html\n```\n\n## Weather Tools\n\nThe FastMCP server provides 4 weather tools for API integration:\n\n### Core Tools\n\n- **`get_weather(zip_code)`**: Get current weather conditions for a ZIP code\n- **`get_forecast(zip_code, days=5)`**: Get weather forecast (1-7 days)\n- **`get_alerts(zip_code)`**: Get active weather alerts (completely free!)\n- **`search_locations(query)`**: Search for locations by name or ZIP code\n\n### API Integration\n\nPerfect for **OpenAI function calling** and other AI service integrations:\n\n```python\n# Example OpenAI function call\ntools = [\n    {\n        \"type\": \"function\",\n        \"function\": {\n            \"name\": \"get_weather\",\n            \"description\": \"Get current weather for a ZIP code\",\n            \"parameters\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"zip_code\": {\"type\": \"string\", \"description\": \"ZIP code (e.g., '10001')\"}\n                },\n                \"required\": [\"zip_code\"]\n            }\n        }\n    }\n]\n```\n\n## FastMCP SSE Integration\n\nThe server uses **FastMCP with SSE transport** for real-time API integration:\n\n### Connection\n```\nServer: http://localhost:8000\nTransport: SSE (Server-Sent Events)\nProtocol: FastMCP\n```\n\n### Tool Calls\nTools are accessible via FastMCP protocol over SSE. Perfect for:\n- **OpenAI function calling**\n- **Claude tool use**\n- **Custom AI integrations**\n- **Real-time weather APIs**\n\n### Interactive Testing\nStart the server and navigate to the test client:\n```bash\nclima-mcp run\n# Then open: http://localhost:8000/\n```\n\n![Clima Demo Interface](docs/images/clima-demo-screenshot.png)\n\n*The interactive test client showing real-time weather data for Erie, CO*\n\nFeatures:\n- Test all 4 weather tools\n- Real-time responses\n- Mock data demonstrations\n- API integration examples\n\n## Example Usage\n\n### Python MCP Client\n\n```python\nfrom weather_mcp import NationalWeatherServiceClient\n\nasync with NationalWeatherServiceClient() as client:\n    # Search by zip code\n    locations = await client.search_locations(\"10001\")\n    location_key = locations[0][\"Key\"]\n\n    # Get current weather\n    weather = await client.get_current_weather(location_key)\n    print(f\"Temperature: {weather.temperature}°{weather.temperature_unit}\")\n\n    # Get alerts (completely free!)\n    alerts = await client.get_weather_alerts(location_key)\n    print(f\"Active alerts: {len(alerts)}\")\n```\n\n### JavaScript SSE Client\n\n```javascript\nconst eventSource = new EventSource('http://localhost:8000/weather/stream/10001');\n\neventSource.addEventListener('weather_update', function(event) {\n    const data = JSON.parse(event.data);\n    console.log(`Temperature: ${data.weather.temperature}°F`);\n});\n\neventSource.addEventListener('weather_alert', function(event) {\n    const data = JSON.parse(event.data);\n    console.log(`Weather Alert: ${data.alerts[0].title}`);\n});\n```\n\n## Coverage Area\n\nThe National Weather Service provides comprehensive coverage for:\n- 🇺🇸 **United States** (all 50 states and territories)\n- **ZIP codes** supported for easy location lookup\n- **Coordinates** for precise location targeting\n- **Puerto Rico, US Virgin Islands, Guam** and other US territories\n\n## Architecture\n\n```\nmain.py (Legacy entry point - use CLI instead)\n├── weather_mcp/\n│   ├── cli.py (Main CLI with FastMCP SSE server)\n│   ├── api_tools.py (FastMCP weather tools)\n│   ├── nws.py (National Weather Service client)\n│   ├── config.py (Configuration management)\n│   ├── models.py (Pydantic data models)\n│   ├── exceptions.py (Custom exceptions)\n│   └── services/ (Service layer architecture)\n│       ├── location_service.py\n│       ├── weather_service.py\n│       ├── forecast_service.py\n│       ├── alert_service.py\n│       ├── raw_weather_service.py\n│       └── testing_service.py\n├── tests/ (Comprehensive test suite)\n│   ├── test_location_service.py\n│   ├── test_weather_service.py\n│   ├── test_forecast_service.py\n│   ├── test_alert_service.py\n│   ├── test_raw_weather_service.py\n│   ├── test_testing_service.py\n│   ├── test_weather_config.py\n│   └── test_weather_server.py\n├── examples/\n│   └── sse_client.html (FastMCP test client)\n├── .github/workflows/ (CI/CD pipelines)\n├── Dockerfile \u0026 docker-compose.yml\n├── pyproject.toml (Modern Python project config)\n├── Makefile (Development commands)\n└── .pre-commit-config.yaml (Code quality automation)\n```\n\n### Service Layer Architecture\n\nThe application follows a clean service-oriented architecture:\n\n- **CLI**: Modern FastMCP server with SSE transport\n- **API Tools**: 4 weather functions for external integration\n- **Services**: Business logic for weather operations\n- **Models**: Pydantic data validation and serialization\n- **Configuration**: Environment-based settings management\n- **Exception Handling**: Custom exceptions for better error management\n\n### Modern Python Project Structure\n\nThe project uses modern Python packaging and tooling:\n\n- **pyproject.toml**: Modern Python project configuration\n- **Ruff**: Fast linting and code formatting\n- **MyPy**: Static type checking\n- **Pre-commit**: Automated quality checks\n- **GitHub Actions**: CI/CD with testing and security scanning\n- **Docker**: Containerized deployment options\n\n## Technical Details\n\n### Data Sources\n\n- **Current Weather**: NWS observation stations\n- **Forecasts**: NWS gridded forecast data\n- **Alerts**: NWS weather alerts and warnings\n- **Location Data**: OpenStreetMap Nominatim geocoding\n\n### Performance\n\n- **No Rate Limits**: Government API with no request restrictions\n- **Caching**: Built-in caching for optimal performance\n- **Async**: Full async/await support for concurrent requests\n- **Real-time**: SSE streaming for live updates\n\n### Reliability\n\n- **Government Source**: Official US National Weather Service data\n- **High Availability**: Government-maintained infrastructure\n- **No API Keys**: No authentication failures or key expiration\n- **Comprehensive Error Handling**: Graceful degradation on failures\n\n## Configuration\n\nThe server can be configured through environment variables or a `.env` file:\n\n```bash\n# Server Configuration\nHOST=localhost\nPORT=8000\nDEBUG=false\nLOG_LEVEL=INFO\n\n# SSE Configuration\nSSE_HEARTBEAT_INTERVAL=30\nSSE_MAX_CONNECTIONS=100\nSSE_CONNECTION_TIMEOUT=300\n\n# Cache Configuration\nCACHE_TTL_SECONDS=300\nCACHE_MAX_SIZE=1000\n```\n\n## Development \u0026 Testing\n\n### Quick Development Commands\n\nThe project includes a comprehensive `Makefile` for easy development:\n\n```bash\n# Development setup\nmake dev-setup          # Full development environment setup\nmake install-dev         # Install with development dependencies\n\n# Code quality\nmake format             # Format code with Black and Ruff\nmake lint               # Run linting checks\nmake type-check         # Run MyPy type checking\nmake pre-commit         # Run pre-commit hooks\n\n# Testing\nmake test              # Run all tests\nmake test-unit         # Run unit tests only\nmake test-integration  # Run integration tests only\nmake coverage          # Run tests with coverage report\n\n# Application\nmake run-test          # Test the NWS API\nmake run               # Run FastMCP server with SSE transport\n\n# Docker\nmake docker-build      # Build Docker image\nmake docker-run        # Run server in Docker container\nmake run-docker-dev    # Start development mode with hot reload\nmake docker-logs       # View Docker logs\nmake docker-stop       # Stop Docker containers\n\n# Cleanup\nmake clean             # Clean build artifacts\n```\n\n### Traditional Testing\n\nRun the comprehensive test suite:\n\n```bash\npython run_tests.py\n```\n\nWith options:\n```bash\npython run_tests.py --type unit --coverage --verbose\npython run_tests.py --type integration --fail-fast\npython run_tests.py --parallel 4\n```\n\n**Test Coverage**:\n- Unit tests for all weather services (individual service test files)\n- Integration tests for MCP and SSE servers\n- Configuration validation tests\n- Mock API responses for CI/CD\n- 56 comprehensive tests with modular structure\n\n### Code Quality Tools\n\nThe project uses modern Python development tools:\n\n- **Black**: Code formatting\n- **Ruff**: Fast linting and import sorting\n- **MyPy**: Static type checking\n- **Pre-commit hooks**: Automated quality checks\n- **Pytest**: Testing framework with async support\n- **GitHub Actions**: Automated CI/CD pipeline\n\n### Development Workflow\n\n1. **Set up environment**:\n   ```bash\n   make dev-setup\n   ```\n\n2. **Make changes and test**:\n   ```bash\n   make format\n   make lint\n   make test\n   ```\n\n3. **Commit changes** (pre-commit hooks run automatically):\n   ```bash\n   git add .\n   git commit -m \"Your changes\"\n   ```\n\n### Docker Development\n\nRun with Docker for consistent environment:\n\n```bash\n# Production mode\ndocker-compose up\n\n# Development mode with hot reload\ndocker-compose --profile dev up\n```\n\n## Contributing\n\nWe welcome contributions! The project includes comprehensive development tools to make contributing easy.\n\n### Development Setup\n\n1. **Fork and clone the repository**\n2. **Set up development environment**:\n   ```bash\n   make dev-setup\n   ```\n3. **Make your changes**\n4. **Run quality checks**:\n   ```bash\n   make format        # Format code\n   make lint          # Check linting\n   make type-check    # Type checking\n   make test          # Run tests\n   ```\n5. **Commit and push** (pre-commit hooks ensure quality)\n6. **Submit a pull request**\n\n### Code Quality Standards\n\n- **Type hints** required for all functions\n- **Docstrings** for all public methods\n- **Tests** for new functionality\n- **Code formatting** with Black\n- **Linting** compliance with Ruff\n- **100% test coverage** for new features\n\n### Continuous Integration\n\nThe project uses GitHub Actions for:\n- **Automated testing** on Python 3.11\n- **Code quality checks** (formatting, linting, type checking)\n- **Security scanning** with Bandit\n- **Coverage reporting** to Codecov\n- **Docker builds** validation\n\n### Project Structure\n\n- Follow the existing service layer architecture\n- Add tests for each new service in corresponding test files\n- Update documentation for new features\n- Use the custom exception classes for error handling\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n- Review the [National Weather Service API documentation](https://www.weather.gov/documentation/services-web-api)\n- Check the [Model Context Protocol specification](https://modelcontextprotocol.io/)\n- Open an issue in this repository\n\n## Badges\n\n![Tests](https://github.com/your-org/clima-mcp/workflows/CI/badge.svg)\n![Python](https://img.shields.io/badge/python-3.11%2B-blue)\n![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)\n![Type checked](https://img.shields.io/badge/mypy-checked-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n## Acknowledgments\n\n- [National Weather Service](https://www.weather.gov/) for providing free, reliable weather data\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification\n- [FastMCP](https://github.com/jlowin/fastmcp) for the modern MCP framework\n- [OpenStreetMap](https://www.openstreetmap.org/) for geocoding services\n- Python community for excellent development tools (Black, Ruff, MyPy, Pytest)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkode-rex%2Fclima","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkode-rex%2Fclima","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkode-rex%2Fclima/lists"}