Skip to content

aashishpanta0/prithvi-wxc-downscaling

v1.0.0

Reproduce NASA PrithviWxC / granite-wxc weather downscaling with portable skills and an MCP tool server.

GitHub

NASA PrithviWxC Downscaling Agent

An AI-powered web app for exploring NASA PrithviWxC downscaling workflows with natural language queries. The project combines a FastAPI chat service, an MCP-backed data tool server, and a browser UI for interactive analysis.

Overview

The system is split into two Python services:

  • agent_server.py runs the chat API and serves the web UI on port 8000.
  • mcp/mcp_server.py exposes the MERRA2 data tools on port 8001.

The frontend in index.html talks to the agent API, and the agent forwards analysis work to the MCP server.

Repository Contents

  • agent_server.py - FastAPI agent service and chat orchestration
  • mcp/mcp_server.py - MCP HTTP server for tool execution
  • mcp/mcp_merra2_tools.py - MERRA2 dataset loading, slicing, plotting, and statistics helpers
  • mcp/mcp-merra2-config.json - Tool manifest used by the MCP server
  • index.html - Browser-based chat UI
  • requirements.txt - Python dependencies
  • .env.sample - Example environment variables
  • chat_history.json - Local conversation history store
  • mcp/artifacts/ - Generated plots and downloadable outputs

Features

  • Natural language climate-data queries
  • Automatic dataset selection for training and inference dates
  • Date parsing for formats like Jan 1, 2024, 2024-01-01, and 20240101
  • Spatial and variable analysis across temperature, humidity, wind, height, and precipitation
  • Downloadable plots and other artifacts from generated analysis
  • Browser UI with chat history support

Prerequisites

  • Python 3.8 or newer
  • Access to Azure OpenAI
  • MERRA2 data available to the MCP tools in the configured data paths

Setup

  1. Create and activate a virtual environment.

  2. Install dependencies:

pip install -r requirements.txt
  1. Configure environment variables by copying the sample file:
cp .env.sample .env
  1. Edit .env and set your Azure OpenAI values:
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
DEPLOYMENT_NAME=your-deployment-name

If your MCP server is running somewhere other than http://localhost:8001, also set MCP_SERVER_URL in .env.

Running Locally

Use start.sh to start, stop and check both servers (MCP server on 8001, agent and UI on 8000):

./start.sh                  # start both (MCP first, then the agent/UI)
./start.sh stop             # stop both
./start.sh restart          # restart both, e.g. after editing the code
./start.sh restart mcp      # restart one server: mcp or ui
./start.sh status           # state, PID, uptime, health check, running jobs
./start.sh logs ui -f       # follow a server's log (mcp or ui); drop -f for the last 100 lines
./start.sh disable          # don't start the servers at boot (enable turns it back on)

On this host the servers run as the systemd user services prithvi-mcp-server and prithvi-agent-ui, and start.sh drives them with systemctl --user. Under systemd they restart automatically 5 s after a crash, but ./start.sh stop keeps them stopped. On a machine without those services, start.sh runs them as background processes and keeps PID and log files in .run/.

Training and inference jobs launched by the MCP server run inside its systemd service, so stopping or restarting the MCP server kills running jobs. start.sh refuses to stop or restart it while jobs are running; wait for them, cancel them, or pass --force. Queued jobs are saved and resume after a restart. Restarting only the UI (./start.sh restart ui) never affects jobs.

To run the servers by hand instead, start the MCP server first and the agent server in a second terminal:

python mcp/mcp_server.py
python agent_server.py

Open the UI in your browser at:

http://localhost:8000

Deployment

This app deploys as two long-running processes. In production, keep the MCP server reachable on 8001 and the agent server reachable on 8000 or behind your reverse proxy.

Typical production flow

  1. Provision a Linux host or container runtime with Python 3.8+.
  2. Install the dependencies from requirements.txt.
  3. Set the environment variables from .env.sample.
  4. Run mcp/mcp_server.py as one service.
  5. Run agent_server.py as a second service.
  6. Put a reverse proxy such as Nginx in front of the agent server if you want HTTPS or a custom domain.

Example service split

  • MCP server: internal-only service on port 8001
  • Agent server: public-facing service on port 8000

If you deploy with systemd, Docker, or another orchestrator, keep the same split and point MCP_SERVER_URL at the MCP service address.

API Endpoints

  • POST /chat - Send a message to the agent
  • GET /health - Health check for the agent server
  • GET /info - Service and tool information
  • GET / - Web UI frontend

The MCP server also exposes:

  • GET /health - MCP health check
  • GET /tools - Tool listing
  • POST /call - Tool execution
  • GET /artifacts/{filename} - Generated artifact download

Data and Outputs

The project is designed around MERRA2 NetCDF data. The exact data paths are configured inside the MCP tools and may point to local or mounted storage in your environment.

Generated plots and other analysis artifacts are written to mcp/artifacts/ and can be downloaded from the UI when available.

Troubleshooting

  • If the agent cannot connect to the MCP server, verify that MCP_SERVER_URL is correct and that port 8001 is open.
  • If you get Azure OpenAI authentication errors, recheck .env and confirm the deployment name matches your Azure setup.
  • If the UI does not load, make sure the agent server is running on port 8000.
  • If data lookups fail, confirm the underlying MERRA2 files are available to the MCP server process.

License

This repository is provided for NASA PrithviWxC downscaling analysis workflows. Add your preferred license before publishing publicly if needed.