\n\n\n```\n\n## Docker Deployment\n\nThe project is available as a Docker image on Docker Hub and includes configurations for easy deployment.\n\n### Quick Start with Docker Hub\n\nPull and run the latest image directly from Docker Hub:\n\n```bash\n# Pull the latest image\ndocker pull dog830228/mcp_weather_server:latest\n\n# Run in stdio mode (default)\ndocker run dog830228/mcp_weather_server:latest\n\n# Run in SSE mode on port 8080\ndocker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse\n\n# Run in streamable-http mode on port 8080\ndocker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http\n\n# Pull a specific version\ndocker pull dog830228/mcp_weather_server:0.5.0\ndocker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse\n```\n\n### Available Docker Images\n\n- **Latest**: `dog830228/mcp_weather_server:latest`\n- **Versioned**: `dog830228/mcp_weather_server:` (e.g., `0.5.0`)\n\nImages are automatically built and published when new versions are released.\n\n### Building from Source\n\nIf you want to build the Docker image yourself:\n\n#### Standard Build\n```bash\n# Build\ndocker build -t mcp-weather-server:sse .\n\n# Run (port will be read from PORT env var, defaults to 8081)\ndocker run -p 8081:8081 mcp-weather-server:sse\n\n# Run with custom port\ndocker run -p 8080:8080 mcp-weather-server:local --mode sse\n```\n\n#### Streamable HTTP Build\n```bash\n# Build using streamable-http Dockerfile\ndocker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .\n\n# Run in stateful mode\ndocker run -p 8080:8080 mcp-weather-server:streamable-http\n\n# Run in stateless mode\ndocker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http\n```\n\n## Development\n\n### Project Structure\n\n```\nmcp_weather_server/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mcp_weather_server/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py # Main MCP server entry point\n\u2502 \u251c\u2500\u2500 server.py # Unified server (stdio, SSE, streamable-http)\n\u2502 \u251c\u2500\u2500 utils.py # Utility functions\n\u2502 \u2514\u2500\u2500 tools/ # Tool implementations\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 toolhandler.py # Base tool handler\n\u2502 \u251c\u2500\u2500 tools_weather.py # Weather-related tools\n\u2502 \u251c\u2500\u2500 tools_time.py # Time-related tools\n\u2502 \u251c\u2500\u2500 tools_air_quality.py # Air quality tools\n\u2502 \u251c\u2500\u2500 weather_service.py # Weather API service\n\u2502 \u2514\u2500\u2500 air_quality_service.py # Air quality API service\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 Dockerfile # Docker configuration for SSE mode\n\u251c\u2500\u2500 Dockerfile.streamable-http # Docker configuration for streamable-http mode\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 requirements.txt\n\u2514\u2500\u2500 README.md\n```\n\n### Running for Development\n\n#### Standard MCP Mode (stdio)\n```bash\n# From project root\npython -m mcp_weather_server\n\n# Or with PYTHONPATH\nexport PYTHONPATH=\"/path/to/mcp_weather_server/src\"\npython -m mcp_weather_server\n```\n\n#### SSE Server Mode\n```bash\n# From project root\npython -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080\n\n# With custom host/port\npython -m mcp_weather_server --mode sse --host localhost --port 3000\n```\n\n#### Streamable HTTP Mode\n```bash\n# Stateful mode (default)\npython -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080\n\n# With debug logging\npython -m mcp_weather_server --mode streamable-http --debug\n```\n\n### Adding New Tools\n\nTo add new weather or time-related tools:\n\n1. Create a new tool handler in the appropriate file under `tools/`\n2. Inherit from the `ToolHandler` base class\n3. Implement the required methods (`get_name`, `get_description`, `call`)\n4. Register the tool in `server.py`\n\n## Dependencies\n\n### Core Dependencies\n- `mcp>=1.0.0` - Model Context Protocol implementation\n- `httpx>=0.28.1` - HTTP client for API requests\n- `python-dateutil>=2.8.2` - Date/time parsing utilities\n\n### SSE Server Dependencies\n- `starlette` - ASGI web framework\n- `uvicorn` - ASGI server\n\n### Development Dependencies\n- `pytest` - Testing framework\n\n## API Data Sources\n\nThis server uses free and open-source APIs:\n\n### Weather Data: [Open-Meteo Weather API](https://open-meteo.com/)\n- Free and open-source\n- No API key required\n- Provides accurate weather forecasts\n- Supports global locations\n- Historical and current weather data\n- Comprehensive metrics (wind, precipitation, UV, visibility)\n\n### Air Quality Data:\n- Free and open-source\n- No API key required\n- Real-time air quality data\n- Multiple pollutant measurements (PM2.5, PM10, O3, NO2, CO, SO2)\n- Global coverage\n- Health-based air quality indices\n\n## Troubleshooting\n\n### Common Issues\n\n**1. City not found**\n- Ensure city names are in English\n- Try using the full city name or include country (e.g., \"Paris, France\")\n- Check spelling of city names\n\n**2. HTTP Server not accessible (SSE or Streamable HTTP)**\n- Verify the server is running with the correct mode:\n - SSE: `python -m mcp_weather_server --mode sse`\n - Streamable HTTP: `python -m mcp_weather_server --mode streamable-http`\n- Check firewall settings for the specified port\n- Ensure all dependencies are installed: `pip install starlette uvicorn`\n- Verify the correct endpoint:\n - SSE: `http://localhost:8080/sse` and `http://localhost:8080/messages/`\n - Streamable HTTP: `http://localhost:8080/mcp`\n\n**3. MCP Client connection issues**\n- Verify Python path in MCP client configuration\n- Check that `mcp_weather_server` package is installed\n- Ensure Python environment has required dependencies\n\n**4. Date format errors**\n- Use ISO 8601 format for dates: YYYY-MM-DD\n- Ensure start_date is before end_date\n- Check that dates are not too far in the future\n\n### Error Responses\n\nThe server returns structured error messages:\n\n```json\n{\n \"error\": \"Could not retrieve coordinates for InvalidCity.\"\n}\n```", "installation_instructions": null, "categories": [ "Everything" ], "owners": [], "owner": null, "code_snippets": { "status": "published", "package_name": "mseep-mcp_weather_server", "package_type": "pypi", "published_url": "https://pypi.org/project/mseep-mcp_weather_server/", "package_version": "0.2.3", "macos_audit_passed": false }, "evaluation_results": [], "found_via_ownership_request": false, "hosting_eligible": false, "knative_enabled": false, "security_scans": [ { "repo_url": "https://github.com/isdaniel/mcp_weather_server", "repo_name": "mcp_weather_server", "score": 100, "risk_level": "low", "score_explanation": "Score starts at 100, deducts points for security issues, and adds points for security best practices", "scan_id": "d47dce7e-10e3-4a1f-a44b-6bf44a482969", "mcp_app_id": "edfc4dd5-c9c0-4e5d-8ad5-64c1dc275da5", "scan_time": "2025-06-08T14:44:23.407245+00:00", "created_at": "2025-06-08T14:44:23.407963+00:00", "updated_at": "2025-06-08T14:44:23.407963+00:00", "findings": [], "vulnerabilities": [] }, { "repo_url": "https://github.com/isdaniel/mcp_weather_server", "repo_name": "mcp_weather_server", "score": 100, "risk_level": "low", "score_explanation": "Score starts at 100, deducts points for security issues, and adds points for security best practices", "scan_id": "afc421f1-87bf-4c3c-ad8e-81e66f99c9d6", "mcp_app_id": "edfc4dd5-c9c0-4e5d-8ad5-64c1dc275da5", "scan_time": "2025-06-13T04:49:22.468285+00:00", "created_at": "2025-06-13T04:49:22.469211+00:00", "updated_at": "2025-06-13T04:49:22.469211+00:00", "findings": [], "vulnerabilities": [] } ] } }