Agentic Web App

An agentic chat application with a React frontend, a FastAPI + CrewAI backend, and three MCP-style tool servers for weather, news, and NASA data.

The system is designed so a single user query can be routed to the right specialists:

• weather_agent for forecasts, geocoding, and weather summaries
• news_agent for article search and live headlines
• nasa_agent for astronomy, asteroid, Mars rover, and Earth imagery data

The backend manager agent decides which specialists are needed, collects their outputs, and returns one final conversational answer to the frontend.

Architecture

React Frontend
  -> POST /chat
FastAPI Backend
  -> CrewAI manager agent
     -> Weather agent -> Weather MCP -> OpenWeather APIs
     -> News agent    -> News MCP    -> NewsAPI
     -> NASA agent    -> NASA MCP    -> api.nasa.gov

Request Flow

1. The user sends a message from the React chat UI.
2. The frontend streams the request to the backend POST /chat endpoint.
3. The backend runs run_crew(user_query) using a hierarchical CrewAI process.
4. The manager agent decides which specialist agents are relevant.
5. Selected specialists call their MCP wrappers.
6. MCP wrappers call the corresponding MCP server /execute endpoint.
7. The MCP server validates input and calls the public upstream API.
8. The manager agent combines the specialist outputs into one final answer.
9. The backend streams the response back to the frontend.

Repository Layout

agentic_web_app/
  backend/              CrewAI orchestration backend
  frontend/             React + Tailwind chat UI
  mcp-servers/          Weather, News, and NASA MCP services
  scripts/              Test runner helpers
  test-logs/            Generated test logs and summaries
  docker-compose.yml    Multi-service local stack
  pytest.ini            Shared pytest markers
  TESTING.md            Detailed testing reference

Module Guide

This section explains the purpose of each important module so it is easier to extend the app safely.

Backend

backend/app/main.py

The FastAPI entrypoint for the backend.

• Loads environment variables with python-dotenv
• Enables CORS for http://localhost:3000 and VITE_FRONTEND_URL
• Exposes POST /chat
• Exposes GET /health
• Logs each request with a timestamp and a truncated query
• Streams the crew response back to the frontend

backend/app/crew/crew.py

The orchestration layer.

• Builds the hierarchical crew
• Creates the manager agent
• Routes queries to weather, news, NASA, or a combination
• Dynamically creates tasks only for selected agents
• Includes the original user query in each task description
• Exposes run_crew(user_query: str) -> str
• Exposes route_query(...) for routing tests

backend/app/agents/weather_agent.py

Defines the Meteorologist agent.

• Goal: analyze weather data and give human-friendly, actionable insight
• Uses all weather tools
• Uses Groq through CrewAI

backend/app/agents/news_agent.py

Defines the News Analyst agent.

• Goal: find and summarize the most relevant news for the user
• Uses all news tools
• Uses Groq through CrewAI

backend/app/agents/nasa_agent.py

Defines the Space Scientist agent.

• Goal: provide space and astronomy insight
• Uses all NASA tools
• Uses Groq through CrewAI

backend/app/tools/weather_tool.py

CrewAI BaseTool wrappers for the weather MCP server.

• Exposes weather tool schemas to the LLM
• Normalizes user or LLM-generated inputs
• Calls WEATHER_MCP_URL/execute
• Returns MCP JSON as a string

Wrapped tools:

• geocode_city
• get_current_and_forecast
• get_historical_weather
• get_daily_aggregation
• get_weather_overview

backend/app/tools/news_tool.py

CrewAI BaseTool wrappers for the News MCP server.

• Exposes Groq-safe tool schemas
• Normalizes query strings, dates, paging, and domain lists
• Calls NEWS_MCP_URL/execute
• Returns MCP JSON as a string

Wrapped tools:

• search_news
• get_top_headlines
• get_news_sources

backend/app/tools/nasa_tool.py

CrewAI BaseTool wrappers for the NASA MCP server.

• Exposes Groq-safe tool schemas
• Handles optional field normalization and fallback defaults
• Calls NASA_MCP_URL/execute
• Returns MCP JSON as a string

Wrapped tools:

• get_astronomy_picture
• get_near_earth_asteroids

MCP Servers

Each MCP service follows the same internal pattern:

• app/main.py: FastAPI entrypoint
• app/server.py: tool registry, request handlers, and execution logic
• app/client.py: HTTP client for the upstream public API
• app/schemas.py: request/response models and input schemas
• tests/: MCP app tests for /health, /tools, and /execute

Each MCP service exposes the same contract:

• GET /health
• GET /tools
• POST /execute

mcp-servers/weather/

Wraps OpenWeatherMap geocoding and One Call 3.0 APIs.

Primary files:

• app/main.py
• app/server.py
• app/client.py
• app/schemas.py

Tools:

• geocode_city
• get_current_and_forecast
• get_historical_weather
• get_daily_aggregation
• get_weather_overview

mcp-servers/news/

Wraps NewsAPI v2.

Primary files:

• app/main.py
• app/server.py
• app/client.py
• app/schemas.py

Tools:

• search_news
• get_top_headlines
• get_news_sources

mcp-servers/nasa/

Wraps NASA public APIs.

Primary files:

• app/main.py
• app/server.py
• app/client.py
• app/schemas.py

Tools:

• get_astronomy_picture
• get_near_earth_asteroids
• get_mars_rover_photos
• get_earth_imagery

Frontend

frontend/src/main.tsx

Bootstraps the React application.

frontend/src/App.tsx

The app shell that mounts the chat interface.

frontend/src/components/ChatInterface.tsx

The main user interface.

• Dark sidebar
• Light chat canvas
• Streaming assistant replies
• Markdown rendering for assistant output
• Inline image rendering for direct image URLs
• Responsive mobile and desktop layout

frontend/src/services/api.ts

Frontend streaming client.

• Reads VITE_BACKEND_URL
• Sends POST /chat
• Consumes the response via ReadableStream
• Emits chunks to the UI as they arrive

frontend/src/index.css

Tailwind setup and shared app styling.

Tests and Tooling

backend/tests/

• test_tool_wrappers.py: unit tests for the CrewAI MCP wrappers
• test_backend_e2e.py: mocked end-to-end crew test
• test_live_smoke.py: live service availability checks
• test_groq_routing_integration.py: real Groq routing verification
• conftest.py: shared pytest setup, env loading, delays, markers

mcp-servers/*/tests/

Service-level tests for MCP endpoints and tool execution.

scripts/run_pytest_group.py

Runs one pytest group and writes a log file under test-logs/.

scripts/run_all_tests.py

Runs all major test groups sequentially with built-in pauses and summary files.

TESTING.md

Testing-specific reference guide with command examples and log behavior.

Prerequisites

For local development:

• Python 3.11+
• Node.js 18+
• npm
• Docker Desktop or Docker Engine with Compose support if you want the containerized stack

You also need API keys for:

• Groq
• OpenWeatherMap
• NewsAPI
• NASA

Environment Files

Create these files from the corresponding .env.example templates:

• backend/.env
• frontend/.env
• mcp-servers/weather/.env
• mcp-servers/news/.env
• mcp-servers/nasa/.env

Recommended backend env

BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=openai/gpt-oss-120b
GROQ_MODEL_AGENTS=openai/gpt-oss-20b
CREWAI_VERBOSE=true
WEATHER_MCP_URL=http://localhost:8001
NEWS_MCP_URL=http://localhost:8002
NASA_MCP_URL=http://localhost:8003
VITE_FRONTEND_URL=http://localhost:3000

Recommended frontend env

VITE_BACKEND_URL=http://localhost:8000
VITE_APP_NAME=Agentic Web App

Weather MCP env

File:

• mcp-servers/weather/.env

Required variables:

• OPENWEATHER_API_KEY: API key for OpenWeatherMap
• OPENWEATHER_GEO_BASE_URL: base URL for the geocoding API
• OPENWEATHER_ONECALL_BASE_URL: base URL for One Call 3.0 endpoints
• MCP_SERVER_HOST: host interface for the FastAPI server
• MCP_SERVER_PORT: service port, expected to be 8001
• MCP_SERVER_NAME: service name returned by /health

OPENWEATHER_API_KEY=your_openweather_api_key
OPENWEATHER_GEO_BASE_URL=https://api.openweathermap.org/geo/1.0
OPENWEATHER_ONECALL_BASE_URL=https://api.openweathermap.org/data/3.0
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8001
MCP_SERVER_NAME=weather-mcp

News MCP env

File:

• mcp-servers/news/.env

Required variables:

• NEWSAPI_KEY: API key for NewsAPI
• NEWSAPI_BASE_URL: base URL for NewsAPI v2
• MCP_SERVER_HOST: host interface for the FastAPI server
• MCP_SERVER_PORT: service port, expected to be 8002
• MCP_SERVER_NAME: service name returned by /health

NEWSAPI_KEY=your_newsapi_key
NEWSAPI_BASE_URL=https://newsapi.org/v2
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8002
MCP_SERVER_NAME=news-mcp

NASA MCP env

File:

• mcp-servers/nasa/.env

Required variables:

• NASA_API_KEY: API key for NASA public APIs
• NASA_BASE_URL: base URL for APOD, Earth imagery, and asteroid endpoints
• NASA_MARS_BASE_URL: base URL for Mars rover photo endpoints
• MCP_SERVER_HOST: host interface for the FastAPI server
• MCP_SERVER_PORT: service port, expected to be 8003
• MCP_SERVER_NAME: service name returned by /health

NASA_API_KEY=your_nasa_api_key
NASA_BASE_URL=https://api.nasa.gov
NASA_MARS_BASE_URL=https://api.mars-photos.nasa.gov
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8003
MCP_SERVER_NAME=nasa-mcp

Replicate The Project Locally

1. Clone the repository

git clone <your-repo-url>
cd agentic_web_app

2. Create environment files

Copy the templates:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
cp mcp-servers/weather/.env.example mcp-servers/weather/.env
cp mcp-servers/news/.env.example mcp-servers/news/.env
cp mcp-servers/nasa/.env.example mcp-servers/nasa/.env

Then fill in your real API keys.

3. Install backend dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r backend/requirements.txt
pip install -r mcp-servers/weather/requirements.txt
pip install -r mcp-servers/news/requirements.txt
pip install -r mcp-servers/nasa/requirements.txt

4. Install frontend dependencies

cd frontend
npm install
cd ..

Run The Entire App Locally

Start the services in this order.

1. Run the weather MCP server

cd mcp-servers/weather
python -m app.main

2. Run the news MCP server

cd mcp-servers/news
python -m app.main

3. Run the NASA MCP server

cd mcp-servers/nasa
python -m app.main

4. Run the backend

cd backend
python -m app.main

5. Run the frontend

cd frontend
npm run dev

6. Open the app

Visit:

http://localhost:3000

Expected local ports

• Frontend: 3000
• Backend: 8000
• Weather MCP: 8001
• News MCP: 8002
• NASA MCP: 8003

Run The Entire App With Docker Compose

Build and start everything:

docker compose up --build

Open:

http://localhost:3000

Compose service map

• frontend -> host port 3000
• backend -> host port 8000
• mcp-weather -> host port 8001
• mcp-news -> host port 8002
• mcp-nasa -> host port 8003

Important Docker note

The frontend uses Vite, which means VITE_* values are baked in at build time. If you change VITE_BACKEND_URL, rebuild the frontend image or rerun docker compose up --build so the new value is included in the static bundle.

Health Checks

You can verify the services individually:

curl http://localhost:8000/health
curl http://localhost:8001/health
curl http://localhost:8002/health
curl http://localhost:8003/health

Testing

Run the full scripted test sequence:

python scripts/run_all_tests.py

Run a single test group:

python scripts/run_pytest_group.py --group mcp-app
python scripts/run_pytest_group.py --group backend-unit
python scripts/run_pytest_group.py --group smoke
python scripts/run_pytest_group.py --group integration

Useful direct pytest commands:

pytest mcp-servers/weather/tests
pytest mcp-servers/news/tests
pytest mcp-servers/nasa/tests
pytest backend/tests/test_tool_wrappers.py
pytest -m smoke
pytest -m integration

For more detail, see TESTING.md.

Common Development Notes

• The backend currently streams the final crew response in chunks after run_crew() returns. It is streaming text to the frontend, but not yet true token-by-token model streaming from Groq.
• The MCP servers are the final validation layer. Tool wrappers should guide and normalize LLM arguments, but the MCP server should still reject invalid requests.
• For host-based smoke tests, use host-reachable URLs such as http://localhost:8001. Docker-internal names like http://mcp-weather:8001 only resolve inside the Compose network.
• If you change frontend dependencies, regenerate frontend/package-lock.json before relying on Docker npm ci.

Troubleshooting

Frontend loads but chat fails

Check:

• frontend/.env contains the correct VITE_BACKEND_URL
• the backend is running on 8000
• CORS is allowing your frontend origin

Backend starts but agent tools fail

Check:

• GROQ_API_KEY is present in backend/.env
• WEATHER_MCP_URL, NEWS_MCP_URL, and NASA_MCP_URL point to reachable services
• the MCP servers are running before the backend

MCP server starts but upstream API fails

Check:

• the service API key is valid
• the upstream API has not rate-limited the request
• the request parameters match the documented schema

Docker frontend points to the wrong backend

Rebuild the frontend image after updating VITE_BACKEND_URL:

docker compose up --build

Suggested First Places To Read

If you are new to the codebase, this is a good reading order:

1. backend/app/main.py
2. backend/app/crew/crew.py
3. backend/app/agents/*.py
4. backend/app/tools/*.py
5. mcp-servers/*/app/server.py
6. frontend/src/components/ChatInterface.tsx
7. frontend/src/services/api.ts

License

Add the project license here if you plan to publish the repository.