# 🌐 Astroseek MCP Integration - UI Guide

**Status**: ✅ Added to HERMES Gradio Interface
**Tab**: External Charts (Astroseek)
**Last Updated**: November 28, 2025

---

## 🎯 What Was Added

A new tab in the HERMES interface that demonstrates external API integration via MCP:

### **New Tab: 🌐 External Charts (Astroseek)**

Located between "Learning Center" and "About" tabs.

**Features**:
1. **Chart Calculator** - Fetch natal chart from Astroseek.com
2. **Daily Horoscope** - Get horoscope by zodiac sign
3. **Full Error Handling** - Graceful degradation if unavailable
4. **Educational Disclaimers** - Clear about limitations

---

## 📊 How to Use

### **On HuggingFace Space**

**URL**: https://huggingface.co/spaces/aamanlamba/hermes-astrology

1. **Wait for rebuild** (~2 minutes after upload)
2. **Hard refresh** browser (Cmd+Shift+R or Ctrl+Shift+R)
3. **Navigate** to "🌐 External Charts (Astroseek)" tab
4. **Try it**:

#### Option 1: Fetch Chart
- Enter birth date (YYYY-MM-DD)
- Enter birth time (HH:MM)
- Enter city name
- Enter country (optional)
- Click "🔍 Fetch Chart from Astroseek"

**Example**:
- Date: 1990-01-15
- Time: 12:00
- City: New York
- Country: USA

#### Option 2: Get Horoscope
- Select zodiac sign from dropdown
- Click "📖 Get Daily Horoscope"

---

## 🎨 UI Components

### **Left Column**: Chart Calculator
```
Birth Date: [YYYY-MM-DD]
Birth Time: [HH:MM]
City: [New York]
Country: [USA] (optional)

[🔍 Fetch Chart from Astroseek]
```

### **Right Column**: Daily Horoscope
```
Zodiac Sign: [Aries ▼]

[📖 Get Daily Horoscope]
```

### **Output Area**
Large text box with:
- Chart data (planets, houses, aspects)
- Horoscope text
- Error messages (if applicable)
- Copy button for easy sharing

---

## ⚠️ Expected Behavior

### **Chart Calculator**

**Success Case** (When working):
```
## 📊 Chart Data from Astroseek.com

Birth Date: 1990-01-15
Birth Time: 12:00
Location: 40.7128, -74.0060

### Planet Positions:
- Sun: 25°17' Capricorn
- Moon: 20°05' Virgo
- Mercury: 11°11' Capricorn
...

Source: horoscopes.astro-seek.com
```

**Error Case** (When scraping fails):
```
## ❌ Error

Error Type: HTTPError
Message: 500 Server Error...

This is a proof-of-concept web scraping integration.
For reliable chart data, use HERMES built-in calculators or official APIs.
```

### **Daily Horoscope**

**Note**: Astro-Seek doesn't provide simple daily horoscope URLs. The feature will return:

```
## ⚠️ Daily Horoscope Not Available

Note: Astro-Seek offers personalized daily horoscopes that require birth chart data.

Alternative: Use the Chart Calculator above to get personalized transit information.

For general daily horoscopes, consider:
- Astrology.com
- Horoscope.com
- AstroStyle
```

---

## 🔧 Technical Details

### **Integration Architecture**

```
User Interface (Gradio)
         ↓
fetch_astroseek_chart()
         ↓
AstroseekMCP Client
         ↓
astroseek_mcp.py
         ↓
BeautifulSoup + Requests
         ↓
Astroseek.com (Web Scraping)
```

### **Code Structure**

**Functions**:
- `fetch_astroseek_chart(date, time, lat, lon)` - Fetch chart data
- `fetch_daily_horoscope(sign)` - Fetch horoscope

**Error Handling**:
- ImportError → Show dependency message
- Connection Error → Show troubleshooting
- Parsing Error → Suggest HTML structure changed
- Generic Exception → Show error type and message

---

## ⚠️ Important Disclaimers (Shown in UI)

### **What it does:**
- Fetches chart data from Astroseek.com
- Demonstrates MCP integration with external services
- Shows how HERMES can connect to third-party APIs

### **Limitations:**
- Web scraping (not an official API)
- Requires internet connection
- May break if Astroseek changes HTML
- Rate limited (1 request/second)
- Subject to Astroseek's terms of service

### **Better Alternatives:**
- Use HERMES built-in calculators (other tabs)
- Swiss Ephemeris via pyswisseph (included)
- Astro.com API (official)
- AstroDienst API

### **Why include this?**
This demonstrates HERMES can integrate with external chart services through the MCP protocol, showing architectural flexibility for the MCP Birthday Hackathon.

**For actual chart analysis, use the HERMES calculators in the other tabs!**

---

## 🎯 Hackathon Value

### **Demonstrates MCP Capabilities**

1. **External Service Integration** ✅
   - Shows MCP can connect to third-party APIs
   - Web scraping as alternative to official APIs

2. **Graceful Degradation** ✅
   - Falls back to built-in calculators if unavailable
   - Clear error messages guide users

3. **Architectural Flexibility** ✅
   - Multiple calculation sources (Modal, Local, Astroseek)
   - MCP protocol enables easy switching

4. **Educational Value** ✅
   - Disclaimers explain limitations
   - Guides users to better alternatives
   - Demonstrates proof-of-concept thinking

---

## 📊 All HERMES Tabs

After this addition, HERMES has **8 comprehensive tabs**:

1. **📊 Chart Analysis** - Essential dignities
2. **⏱️ Time Lords** - Annual profections
3. **📐 Bounds & Decans** - Egyptian terms and faces
4. **🌟 Zodiacal Releasing** - Valens time-lord system
5. **🎓 Learning Center** - AI teaching mode
6. **🌐 External Charts (Astroseek)** - NEW! External API integration
7. **ℹ️ About** - Project information

---

## 🐛 Troubleshooting

### **"I don't see the new tab"**
- Hard refresh (Cmd+Shift+R)
- Check HuggingFace Logs for rebuild completion
- Wait 2-3 minutes after upload

### **"Chart fetch fails immediately"**
Expected behavior! Web scraping is fragile:
- Use HERMES built-in calculators instead
- This tab demonstrates MCP integration concept
- Not meant for production chart calculations

### **"Dependencies not found"**
- requirements.txt includes beautifulsoup4, lxml, requests
- HuggingFace should install automatically
- Check Space logs for build errors

### **"Daily horoscope returns error"**
Also expected! Astroseek may:
- Block automated requests
- Change HTML structure
- Rate limit requests

**This is fine** - it's a proof-of-concept for the hackathon!

---

## 🎊 Summary

**Astroseek integration is now live in the UI!**

### ✅ What Users Can Do
- Try fetching charts from external source
- Get daily horoscopes (if available)
- See MCP integration in action
- Understand limitations of web scraping

### ✅ What It Demonstrates
- HERMES can connect to external services
- MCP protocol enables third-party integration
- Graceful error handling and fallback
- Educational approach to proof-of-concept features

### 🎯 Bottom Line
This completes the **triple MCP integration showcase**:
1. **Modal** - Serverless calculations
2. **Local** - Offline fallback
3. **Astroseek** - External service integration

All integrated through the **Model Context Protocol (MCP)** architecture!

---

**Space URL**: https://huggingface.co/spaces/aamanlamba/hermes-astrology
**Rebuild Time**: ~2 minutes
**Status**: ✅ DEPLOYED

🎉 **Ready for hackathon demonstration!**