\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```\n\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": [] } ] } }