# 🚀 NASA Space Explorer — Cliente MCP

Asistente de astronomía en tiempo real con datos de la NASA. Inspirado en Carl Sagan: **preciso y apasionante**.

---

## Arquitectura

```
nasa_client.py              nasa_server.py
──────────────              ──────────────
  Menú + display  ──MCP──►  5 herramientas NASA
  Lenguaje natural ◄──────  APIs: APOD · NeoWs · Mars · EONET · DONKI
```

El cliente lanza `nasa_server.py` como subproceso y se comunican por `stdio` usando el protocolo MCP. **No necesitas Docker ni API key** para empezar.

---

## Requisitos previos

| Herramienta | Versión | Comprobación |
|-------------|---------|--------------|
| Python | 3.10+ | `python --version` |
| Conexión a internet | — | Para llamar a las APIs de la NASA |

---

## 1 — Instalación

```powershell
# Desde la carpeta del proyecto
cd C:\Users\Alumno_AI\Documents\mcp-espacial

# Crear entorno virtual
python -m venv .venv
.venv\Scripts\Activate.ps1

# Instalar dependencias
pip install "mcp[cli]" httpx
```

---

## 2 — Ejecutar

```powershell
python nasa_client.py
```

Verás:

```
╭─────────────────────────────────────╮
│  🚀  NASA Space Explorer            │
│  Sistema MCP de datos espaciales    │
╰─────────────────────────────────────╯

Puedes escribir preguntas en lenguaje natural o usar el menú:
  1) Imagen astronómica del día (APOD)
  2) Asteroides cercanos a la Tierra esta semana
  3) Fotos del rover en Marte
  4) Eventos naturales activos en la Tierra
  5) Clima espacial (llamaradas, CMEs, tormentas)
  0) Salir

🚀 NASA Explorer >
```

---

## 3 — Herramientas MCP disponibles

| # | Tool MCP | Datos | API |
|---|----------|-------|-----|
| 1 | `get_astronomy_picture_of_the_day` | Imagen + explicación científica | NASA APOD |
| 2 | `search_near_earth_objects` | Asteroides, distancia, velocidad, peligrosidad | NASA NeoWs |
| 3 | `get_mars_rover_photos` | Fotos con URL, cámara, fecha marciana | NASA Mars Rover Photos |
| 4 | `track_earth_natural_events` | Incendios, volcanes, tormentas activas | NASA EONET |
| 5 | `get_space_weather` | Llamaradas solares, CMEs, índice Kp | NASA DONKI |

---

## 4 — Uso con lenguaje natural

El cliente detecta automáticamente la herramienta correcta:

| Lo que escribes | Herramienta que se llama |
|----------------|--------------------------|
| `¿Cuál es la imagen del día?` | `get_astronomy_picture_of_the_day` |
| `¿Hay asteroides peligrosos esta semana?` | `search_near_earth_objects` |
| `fotos de Perseverance sol 500` | `get_mars_rover_photos(rover=perseverance, sol=500)` |
| `¿Hay incendios activos?` | `track_earth_natural_events(category=wildfires)` |
| `llamaradas solares esta semana` | `get_space_weather(event_type=flares)` |
| `clima espacial` | `get_space_weather(event_type=all)` |
| `volcanes activos` | `track_earth_natural_events(category=volcanoes)` |

---

## 5 — Ejemplos de salida

### Asteroides (opción 2)
```
☄️  Objetos Cercanos a la Tierra — 2026-06-17 → 2026-06-24

Total detectados: 23 objetos
✓  Ninguno clasificado como potencialmente peligroso

┌────────────────────┬──────────────┬─────────────┬───────────────┬────────────┐
│ Nombre             │ Ø km         │ Distancia km│ Dist. lunar   │ Vel. km/h  │
├────────────────────┼──────────────┼─────────────┼───────────────┼────────────┤
│ (2024 AB1)         │ 0.014–0.031  │ 1,234,567   │ 3.21 ☽        │ 42,300     │
└────────────────────┴──────────────┴─────────────┴───────────────┴────────────┘
```

### Clima espacial (opción 5)
```
☀️  Clima Espacial — 2026-06-10 → 2026-06-17

🔥 Llamaradas solares: 3
  • 2026-06-15 08:23  Clase: M2.1  Región: 13842
  • 2026-06-16 14:05  Clase: C7.4  Región: 13845

💨 Eyecciones de masa coronal (CME): 1
  • 2026-06-15 10:00  Velocidad: 847 km/s  Tipo: O

🌩  Tormentas geomagnéticas: 0
  ✓  Sin tormentas geomagnéticas registradas.
```

---

## 6 — Configuración del `.env`

Copia el archivo de ejemplo y rellena tus credenciales:

```powershell
Copy-Item .env.example .env
```

Edita `.env`:

```env
# ── Azure OpenAI (para activar la IA conversacional) ──
AZURE_OPENAI_ENDPOINT=https://TU-RECURSO.openai.azure.com/
AZURE_OPENAI_KEY=TU_CLAVE_AQUI
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_OPENAI_API_VERSION=2024-12-01-preview

# ── NASA API (opcional, DEMO_KEY funciona sin registrarse) ──
NASA_API_KEY=DEMO_KEY
```

> [!IMPORTANT]
> Sin Azure OpenAI el cliente funciona en **modo local** (muestra JSON de la API sin interpretación LLM).
> Con Azure OpenAI activado, GPT-4o interpreta los datos y responde en lenguaje natural estilo Carl Sagan.

### Instalar dependencia extra para Azure

```powershell
pip install openai python-dotenv
```

### Dónde encontrar las credenciales Azure

| Variable | Dónde encontrarla |
|----------|--------------------|
| `AZURE_OPENAI_ENDPOINT` | Azure Portal → tu recurso OpenAI → Keys and Endpoint |
| `AZURE_OPENAI_KEY` | Azure Portal → tu recurso OpenAI → Keys and Endpoint |
| `AZURE_OPENAI_DEPLOYMENT` | Azure AI Foundry → Deployments → nombre del modelo |
| `AZURE_OPENAI_API_VERSION` | Usar `2024-12-01-preview` (compatible con tool calling) |

### NASA API Key (opcional)

NASA ofrece claves gratuitas sin límites estrictos:
1. Regístrate en **https://api.nasa.gov/**
2. Pon tu clave en `.env` como `NASA_API_KEY=tu_clave`

---

## 7 — Rovers de Marte disponibles

| Rover | Estado | Sols activos aprox. | Cámaras principales |
|-------|--------|---------------------|---------------------|
| Curiosity | ✅ Activo | 1 – 4300+ | NAVCAM, MAST, FHAZ, RHAZ, CHEMCAM |
| Perseverance | ✅ Activo | 1 – 1500+ | NAVCAM_LEFT, NAVCAM_RIGHT, MCZ_LEFT, MCZ_RIGHT |
| Opportunity | ❌ Inactivo (2019) | 1 – 5111 | PANCAM, NAVCAM, FHAZ, RHAZ |
| Spirit | ❌ Inactivo (2010) | 1 – 2208 | PANCAM, NAVCAM, FHAZ, RHAZ |

> [!TIP]
> Si no hay fotos para un sol concreto, prueba con un número distinto. No todos los soles tienen fotos de todas las cámaras.

---

## 8 — Clasificación de llamaradas solares

| Clase | Intensidad | Efecto en Tierra |
|-------|-----------|-----------------|
| A, B | Mínima/Débil | Sin efecto apreciable |
| C | Moderada | Perturbaciones radio en zonas polares |
| M | Intensa | Apagones radio, auroras débiles |
| **X** | **Extrema** | **Apagones radio, tormentas geomagnéticas** |

El índice **Kp** mide la perturbación del campo magnético terrestre (0=calma, 9=extrema). Kp ≥ 5 = tormenta geomagnética; pueden verse auroras boreales en latitudes medias.

---

## 9 — Estructura del proyecto

```
mcp-espacial/
├── nasa_client.py   ← Ejecutar este
├── nasa_server.py   ← Servidor MCP (lanzado automáticamente)
└── README.md        ← Esta guía
```

---

## 10 — Referencias

- [NASA APIs](https://api.nasa.gov/)
- [APOD](https://apod.nasa.gov/apod/)
- [NeoWs — Near Earth Objects](https://api.nasa.gov/#NeoWS)
- [Mars Rover Photos](https://api.nasa.gov/#Mars-Rover-Photos)
- [NASA EONET](https://eonet.gsfc.nasa.gov/)
- [NASA DONKI — Space Weather](https://kauai.ccmc.gsfc.nasa.gov/DONKI/)
- [MCP SDK Python](https://github.com/modelcontextprotocol/python-sdk)

---

> *"Somewhere, something incredible is waiting to be known."* — Carl Sagan