Weather MCP demo (Python)

This project demonstrates the complete flow requested in the onboarding task:

User query -> sample agent / Codex -> MCP tool -> REST API -> 4-field response

It contains three sample REST APIs backed by live US National Weather Service (NWS) data and three matching MCP tools:

User intent	REST API	MCP tool
Current weather	GET /api/weather/current	get_weather
1-7 day forecast	GET /api/weather/forecast	get_forecast
Weather warnings	GET /api/weather/alerts	get_weather_alerts

Every API returns exactly four top-level attributes:

{
  "id": "demo-1",
  "location": "Chicago",
  "status": "success",
  "data": {}
}

The MCP input schemas intentionally mirror the API query parameters. FastMCP derives JSON Schema from the Python function type hints and validates tool calls.

1. Install

Python 3.11+ is required.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

2. Start the sample APIs

Keep this terminal running:

source .venv/bin/activate
python -m uvicorn weather_mcp.api:app --host 127.0.0.1 --port 8000

Useful pages:

• Swagger UI: http://127.0.0.1:8000/docs
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json

Try an API directly:

curl "http://127.0.0.1:8000/api/weather/current?id=demo-1&city=Chicago"

3. Run the sample agent

In a second terminal:

source .venv/bin/activate
python -m weather_mcp.agent "What is the current weather in Chicago? id: demo-1"
python -m weather_mcp.agent "Give me the 5 day forecast for New York. id: demo-2"
python -m weather_mcp.agent "Are there any severe weather alerts in Miami? id: demo-3"

The agent is deliberately deterministic and local, so it needs no model API key. It still uses a real MCP client session: it launches the MCP server, lists its tools, selects one from the user intent, and invokes it over stdio.

4. Connect it to Codex

First start the REST API as shown above. This checkout already includes .codex/config.toml with the correct absolute paths. Restart/open a new Codex task in this trusted project so Codex loads the weather MCP server.

If the project is moved or cloned elsewhere, copy .codex/config.toml.example to .codex/config.toml and replace both absolute paths.

Example prompts:

• "Use the weather tool to get current conditions in Chicago. ID: codex-1."
• "Get the 4 day forecast for New York. ID: codex-2."
• "Are there any active weather alerts in Miami? ID: codex-3."

Codex acts as the intelligent agent/host: it reads the tool names, descriptions, and input schemas exposed by this server and chooses the appropriate MCP tool.

5. Test

source .venv/bin/activate
pytest -q

Design notes

• weather_mcp/api.py is the API layer.
• weather_mcp/server.py is the MCP connector sitting on top of the APIs.
• weather_mcp/agent.py is a minimal local agent and MCP client.
• weather_mcp/models.py defines the stable four-field response contract.
• Weather and alert data comes from api.weather.gov.
• City names are geocoded through Open-Meteo's geocoding endpoint because NWS accepts coordinates rather than city names.
• NWS covers US locations only. Prefer City, State when a name is ambiguous.
• Set NWS_USER_AGENT to an application name and contact address in production.
• NWS requests can occasionally fail or time out; the REST layer maps upstream failures to clear 502/503 responses and MCP returns them as tool errors.
• MCP uses stdio locally; stdout is reserved for protocol traffic.