Astro Agent

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.

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.

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.

---

🚀 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):

{
  "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:

# ====================================================================
# 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

npm install

2. Run Local Development Server

Launches the dual-channel Express.js proxy and integrates Vite's frontend bundler simultaneously on port 3000:

npm run dev

Open 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:

# Bundle Frontend and Backend
npm run build

# Start production server
npm start