# 🌌 Astro Agent — Space Telemetry & Celestial AI Dashboard

Astro Agent is an immersive, full-stack web application designed for astronomical research, live satellite tracking, and cosmic exploration. Built with an elegant, glassmorphic dark user interface, it provides a unified hub for real-time aerospace telemetry, celestial constellation mapping, and an intelligent space-focused conversational agent.

The application leverages a robust React (Vite) frontend paired with a secure Express.js server, ensuring responsive performance and complete protection of sensitive API credentials.

---

## 🎨 Application Previews

### 1. Astro Agent Dashboard (Homepage)
The main homepage features a professional, high-fidelity three-column dashboard layout designed for maximum scannability and modular data integration:
- **Left Column:** Live telemetry trackers including Quick Telemetry Scan hot-probes (Satellite, Solar, and Planetary), a click-to-expand NASA APOD thumbnail card, and the main ISS Downlink console showing essential coordinate tracking stats.
- **Center Column:** The Astro Agent Chat Interface, powered by server-side Gemini AI, allowing users to send custom telemetry context probes or query celestial phenomena.
- **Right Column:** Dynamic network diagnostics displaying uplink status and the live geocentric Polar Constellation Radar with interactive observer location presets.

![Astro Agent Homepage](src/assets/images/dashboard.png)

### 2. Expanded ISS Telemetry Console (Sidebar / Popup)
Clicking the ISS Telemetry block or the expand button triggers a dense, telemetry-focused modal console. It displays a real-time tracking reticle over an orbit image of the ISS, synchronized cockpit clock parameters, and precise sliders mapping Latitude, Longitude, Altitude, Orbit Speed, Solar Collection Efficiency, and Communication Link channels.

![Expanded ISS Telemetry Popup](src/assets/images/iss.png)
![Expanded ISS Telemetry Popup](src/assets/images/iss2.png)

### 3. NASA APOD Detailed Viewer (Popup)
Clicking the NASA Picture of the Day (APOD) card opens an elegant overlay modal. It displays a stunning high-resolution view of the cosmic image (or video frame) on the left side, and a scrollable technical documentation panel explaining the capture on the right.

![NASA APOD Popup](src/assets/images/apod.png)

---

## 🚀 Key Features & Workflows

### 1. Real-Time Satellite Tracking Downlink
- **10s Interval Polling:** Every 10 seconds, the client fetches fresh orbital telemetry from the server proxy `/api/iss-telemetry`.
- **Elapsed-Time Tickers:** Live indicators display exactly how many seconds have elapsed since the last downlink was received, preventing stale telemetry.
- **Self-Healing Fallbacks:** Built-in network check boundaries automatically switch the ISS viewport to a flat vector blueprint layout if remote image CDNs fail, maintaining cockpit operational status.

### 2. Secure Server-Side Gemini AI (Astro Core)
- **Prompt Injection Probes:** Hot-probe telemetry buttons ("Scan Satellites", "Solar Activity", "Planetary Status") dynamically build structured astronomical queries and feed them to Gemini.
- **Contextual Understanding:** The AI is pre-tuned to act as a cosmic-focused astrodynamics agent, utilizing custom prompts and diagnostic contexts.

### 3. Celestial Star Constellation Radar
- **Polar Projections:** Projects active celestial offsets onto a rotating client-side SVG polar coordinate radar.
- **Observer Location Presets:** Seamless dropdown options update the geocentric observer coordinates instantly (presets for Sydney, Houston, Svalbard, Tokyo, etc.).

### 4. Fully-Compliant Model Context Protocol (MCP) Server
Astro Agent exposes a native, standard-compliant **Model Context Protocol (MCP)** server on its Express.js backend, allowing external AI clients, coding assistants, or LLMs to fetch live astronomical telemetry securely:
- **Dual Transports:** Supports both standard **SSE (Server-Sent Events)** stream-routing and lightweight direct **JSON-RPC 2.0 HTTP POST** triggers.
- **Registered Tools:**
  - `get_iss_telemetry`: Queries live orbital positions, velocity parameters, altitude tracking, thermal grids, and solar battery efficiencies.
  - `get_apod`: Delivers the Astronomy Picture of the Day containing full scientific description logs.
  - `get_solar_weather`: Pulls active sunspot sweeps, solar wind estimates, flare warnings, and auroral probabilities.

---

## 🔌 Integrating the MCP Server (Claude Desktop / Cursor)

To allow external LLM clients to read live data from your Astro Agent tools, configure the server in your local client setup files:

### For Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "nasa-astro-agent": {
      "command": "node",
      "args": ["/absolute/path/to/astro-agent/dist/server.cjs"],
      "env": {
        "NASA_API_KEY": "your_nasa_api_key_here",
        "NODE_ENV": "production"
      }
    }
  }
}
```

### For Real-Time SSE Transport:
Simply stream directly from the active running cockpit instance:
- **SSE Endpoint:** `http://localhost:3000/api/mcp/sse`
- **POST Message Route:** `http://localhost:3000/api/mcp/message`

---

## 🔒 Security & Safe GitHub Publishing (No Exposed API Keys)

Astro Agent is fully optimized for public publishing to platforms like **GitHub** without any risk of exposing your private API keys. It adheres to strict modern security best practices:

1. **Full-Stack Proxying:** All queries to external APIs (Google Gemini, NASA APIs) are processed **server-side** via secure backend routes. The frontend makes simple requests to relative local endpoints:
   - `/api/chat`
   - `/api/apod`
   - `/api/iss-telemetry`
2. **Environment Isolation:** API keys are never written, embedded, or hardcoded into the React codebase. Instead, they are retrieved from environment variables inside Node's execution context:
   - `process.env.GEMINI_API_KEY`
   - `process.env.NASA_API_KEY`
3. **Secure .gitignore Rules:** The project includes a preconfigured `.gitignore` file that safely blocks local `.env` credential files from ever being added to a Git commit, while allowing `.env.example` to serve as an open, clean template.

---

## ⚙️ Environment Variables

Copy the structure of `.env.example` and save it as `.env` in the root folder of your project prior to starting:

```env
# ====================================================================
# ASTRO AGENT SYSTEM CREDENTIALS
# ====================================================================

# Google Gemini AI Key (Retrieve from Google AI Studio: https://aistudio.google.com)
# If left blank, Astro Agent runs in offline simulation backup mode.
GEMINI_API_KEY="AIzaSyYourSecretGeminiAPIKeyHere"

# NASA Open API Key (Retrieve instantly from https://api.nasa.gov)
# If left blank, the app gracefully falls back to rate-limited DEMO_KEY.
NASA_API_KEY="YourSecretNasaAPIKeyHere"

# Environment Settings
NODE_ENV="production"
PORT=3000
```

---

## 🛠️ Installation & Compilation

Ensure Node.js is installed locally on your system, then follow these commands to launch:

### 1. Retrieve Packages
```bash
npm install
```

### 2. Run Local Development Server
Launches the dual-channel Express.js proxy and integrates Vite's frontend bundler simultaneously on **port 3000**:
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser.

### 3. Compile & Start in Production
Bundle the React client into high-performance static files, bundle the backend Node code into optimized CommonJS, and start the production build:
```bash
# Bundle Frontend and Backend
npm run build

# Start production server
npm start
```