Weather Travel Advisory Server

An MCP (Model Context Protocol) server that exposes weather-related tools, resources, and prompts, using the public wttr.in weather API to generate a structured, deterministic travel advisory report.

This implements the PRD: P004 Case Study 2: Weather and Travel Advisory MCP Server Using wttr.in API. Section references below (e.g. "PRD 10.3") point back to that document.

---

1. Project Overview

The server accepts a destination city, fetches live weather data, normalizes it into a clean schema, deterministically calculates a travel weather risk (LOW / MEDIUM / HIGH), and produces a JSON travel advisory report — all through well-defined MCP primitives rather than a generic chatbot loop.

2. Business Use Case

A traveler wants a quick, structured answer to questions like:

• "Should I travel to Jaipur this weekend?"
• "What should I pack for Pune based on the weather?"
• "Is Mumbai risky for outdoor travel?"

Out of scope (PRD Section 5): flight/hotel/train booking, medical advice, disaster alerts, visa/immigration rules, paid travel services. This is a weather-based advisory only, not a guaranteed travel decision.

3. Technology Stack

Layer	Choice
MCP framework	mcp (FastMCP)
HTTP client	requests
Data validation	pydantic
Testing	pytest, pytest-mock
Config	python-dotenv
Language	Python 3.10+

4. wttr.in API Usage Details (PRD Section 6–7)

• Endpoint: GET https://wttr.in/{city_name}?format=j1
• No API key required.
• Fallback domain: https://wttr.is/{city_name}?format=j1
• City names with spaces: replace spaces with + (e.g. New+Delhi).
• Timeout: 10 seconds.
• Numeric fields in the raw response arrive as strings and are converted to int/float during normalization (PRD 7.6).

All networking lives in src/api_client.py. Per PRD Section 9, it is the only module that talks to the wttr.in API.

5. MCP Tools (PRD Section 10)

Tool	Purpose
validate_city_input_tool	Validates/cleans the destination city name. No API call.
get_weather_forecast_tool	Calls wttr.in (only tool allowed to hit the network).
normalize_weather_data_tool	Converts raw wttr.in JSON into the normalized schema.
calculate_weather_risk_tool	Deterministic LOW/MEDIUM/HIGH risk calculation. No LLM.
save_travel_advisory_tool	Validates + saves the final report as JSON.

6. MCP Resources (PRD Section 11)

Resource URI	Content
resource://travel/checklist	Static travel-readiness checklist
resource://travel/advisory-rules	Static LOW/MEDIUM/HIGH interpretation rules
resource://weather/normalized-forecast-schema	JSON description of the normalized schema

Resources are static reference content only — they never call APIs.

7. MCP Prompts (PRD Section 12)

Prompt	Purpose
travel_readiness_prompt	Template for a concise travel-readiness advisory
weather_risk_summary_prompt	Template explaining why the risk level was assigned
packing_recommendation_prompt	Template for practical packing suggestions

Prompts only render natural-language template text — they never call APIs and never perform risk math (that's calculate_weather_risk_tool's job).

8. Setup Instructions

git clone <this-repo>
cd p004_mcp_weather_travel_advisory
python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
pip install -r requirements.txt
cp .env.example .env   # no API key needed, defaults already work

9. How to Run the MCP Server

python src/server.py

This starts the MCP server on stdio transport, ready to be connected from any MCP-compatible client (e.g. Claude Desktop, an MCP Inspector, or a custom client configured to launch this command).

10. How to Run Tests

pytest tests/

This runs all unit tests (37 tests) using mocked wttr.in responses — no network access or API key required. pytest.ini excludes integration tests by default (-m "not integration").

11. How to Run Integration Tests

pytest -m integration

This runs test_real_wttr_api_for_jaipur, which makes a real HTTP call to wttr.in. Status: written but unverified in this delivery — the development sandbox used to build this project only allowed network egress to package registries (PyPI/npm/GitHub), not to wttr.in/wttr.is, so this specific test could not be executed live here. It is ready to run in any environment with normal internet access.

12. How to Generate Sample Reports

python src/server.py --sample-city Jaipur
python src/server.py --sample-city Pune

Each command runs the full PRD Section 13 pipeline once and prints the resulting JSON report, saving it to outputs/travel_advisory_report.json. Pre-generated examples (built from mocked weather data, since this sandbox cannot reach wttr.in) are checked in at:

• sample_outputs/sample_jaipur_advisory.json (MEDIUM risk scenario)
• sample_outputs/sample_pune_advisory.json (HIGH risk scenario)

13. Final Report Schema (PRD Section 14)

{
  "destination": "",
  "region": "",
  "country": "",
  "forecast_days": 3,
  "current_weather": {
    "temperature_c": 0,
    "humidity": 0,
    "precipitation_mm": 0,
    "wind_speed_kmph": 0,
    "weather_description": ""
  },
  "daily_forecast": [
    {
      "date": "",
      "max_temp_c": 0,
      "min_temp_c": 0,
      "avg_temp_c": 0,
      "total_precipitation_mm": 0,
      "max_wind_kmph": 0,
      "max_chance_of_rain": 0,
      "weather_description": ""
    }
  ],
  "weather_risk": "LOW | MEDIUM | HIGH",
  "risk_factors": [],
  "recommended_actions": [],
  "packing_suggestions": [],
  "travel_readiness_advisory": "",
  "weather_risk_explanation": "",
  "resources_used": [],
  "tools_used": [],
  "prompts_used": []
}

The report is validated against this schema (via src/schemas.py, a pydantic model) before it is written to disk.

14. Known Limitations

1. No live LLM call for prompt outputs. travel_readiness_advisory, weather_risk_explanation, and packing_suggestions are conceptually meant to be produced by feeding the rendered prompt templates (PRD Section 12) to an LLM. This environment has no LLM API key / network access to an LLM provider, so src/server.py::_render_llm_field contains the intended (commented-out) Anthropic API call, clearly marked "written but unverified — no API key/network access to test live", and falls back to a small deterministic text generator so the pipeline still produces a complete, schema-valid report end to end.
2. No live wttr.in access from the build sandbox. The environment used to build and test this project could only reach package registries (PyPI, npm, GitHub), not wttr.in/wttr.is. All unit tests therefore use realistic mocked fixtures (tests/conftest.py), and the one real-network test is marked @pytest.mark.integration and flagged as unverified here.
3. Risk model is a fixed rule set. Thresholds (e.g. max_temp_c >= 40) come directly from PRD Section 10.4 and are not configurable via environment variables in this version.
4. 3-day forecast cap. Per PRD 10.3 rule 5, only the first 3 days returned by wttr.in are normalized, even if more are available.

15. Future Improvements

• Wire up the real Anthropic Messages API call in _render_llm_field once an API key is available, and add a live/offline toggle via an env var.
• Add response caching for repeated queries to the same city within a short time window, to reduce load on wttr.in.
• Make risk thresholds configurable via .env for easier tuning.
• Add more cities to sample_outputs/ (New Delhi, Mumbai, Bengaluru) once live API access is available.
• Add an MCP resource that returns the list of supported/validated example cities for quick client-side testing.

---

Project Structure

p004_mcp_weather_travel_advisory/
├── README.md
├── requirements.txt
├── .env.example
├── pytest.ini
├── src/
│   ├── server.py          # MCP server wiring + orchestration flow (PRD 13)
│   ├── tools.py            # 5 mandatory MCP tools (PRD 10)
│   ├── resources.py        # 3 mandatory MCP resources (PRD 11)
│   ├── prompts.py          # 3 mandatory MCP prompts (PRD 12)
│   ├── api_client.py       # wttr.in HTTP client (PRD 6, 7, 18)
│   ├── schemas.py          # pydantic schemas (PRD 10.3, 14)
│   └── report_writer.py    # JSON persistence + schema validation (PRD 10.5)
├── tests/
│   ├── conftest.py             # mocked wttr.in fixtures
│   ├── test_api_client.py
│   ├── test_tools.py
│   ├── test_resources.py
│   ├── test_prompts.py
│   └── test_report_schema.py
├── outputs/
│   └── travel_advisory_report.json   # generated at runtime
└── sample_outputs/
    ├── sample_jaipur_advisory.json
    └── sample_pune_advisory.json