🏛️ HERMES - Hellenistic Ephemeris Research & MCP Educational System

Ancient Wisdom Meets Modern AI Through the Model Context Protocol

✨ What is HERMES?

An interactive research and teaching tool for traditional Hellenistic astrology, combining 2000-year-old techniques from ancient Greek and Roman astrologers with modern AI agents and the Model Context Protocol (MCP).

✨ What You Can Do Here:

📊 Chart Calculations

  • Essential Dignities - Assess planetary strength through domicile, exaltation, and triplicity
  • Traditional Lots - Calculate the Lots of Fortune and Spirit with proper sect consideration
  • Egyptian Bounds - Determine bound (term) rulers for refined dignity assessment
  • Decans (Faces) - Find decan rulers following the Chaldean order

⏱️ Time-Lord Techniques

  • Annual Profections - Discover your Lord of the Year for any age
  • Zodiacal Releasing - Explore major life periods from Vettius Valens' system

🎓 Learn Traditional Astrology

  • Text-Based Teaching - AI-powered explanations of Hellenistic techniques
  • Source Research - Educational content citing ancient texts
  • Study Resources - Curated books, courses, and free learning materials

🌐 External Integrations

  • Astroseek MCP - Fetch chart data from external sources (proof-of-concept)
  • Modal Serverless - 6 MCP functions deployed for calculations
  • Local Fallback - All calculations available offline

🏛️ Built on Ancient Foundations

All techniques are drawn from authentic Hellenistic sources (1st-7th century CE), not modern psychological astrology. We preserve the traditional methods exactly as taught by Valens, Ptolemy, and Dorotheus.

Built for the MCP 1st Birthday Hackathon | Powered by OpenAI, Anthropic, ElevenLabs & Modal

🌐 Model Context Protocol (MCP) Integration Showcase

HERMES demonstrates the power of MCP by integrating 5 different calculation backends:

  1. 🏠 Local MCP - Core features running locally
  2. ☁️ Modal Serverless - Cloud-deployed time-lord calculations
  3. 🔮 Astroseek.com - External chart data via web scraping
  4. 📊 Astro.com - Classical Hellenistic chart generation
  5. 🤖 Google Gemini AI - Natural language astrology conversations

Why MCP Matters for HERMES

The Model Context Protocol allows HERMES to:

  • Scale: Offload heavy calculations to cloud (Modal)
  • Integrate: Connect to third-party services (Astroseek, Astro.com)
  • Converse: Use AI for educational explanations (Gemini)
  • Fallback: Gracefully degrade when services unavailable
  • Extend: Easy to add new calculation sources

Local MCP Server

Runs directly on your machine with instant responses.

Features:

  • Essential Dignities (5-level system)
  • Annual Profections
  • Lot of Fortune calculations
  • Educational explanations

Status: ✅ Always Available (no internet required)

Test Essential Dignity
Planet
Sign

Modal Serverless MCP

Cloud-deployed calculation functions on Modal infrastructure.

Features:

  • Zodiacal Releasing
  • Firdaria
  • Bounds & Decans
  • Essential Dignities (cloud version)
  • Fixed Stars

Status: ✅ Deployed at modal.com Endpoint: modal app list to view deployment

Benefits:

  • Zero local compute overhead
  • Scales automatically
  • Same API as local MCP
  • Graceful fallback to local

Test it: Use the Time Lords tab - calculations run on Modal!

Astro.com Classical Chart Generator

Generate classical Hellenistic charts using Astro.com infrastructure.

Features:

  • Whole Sign house system
  • Traditional aspects
  • Chart URL generation
  • Hellenistic interpretation guides

Status: 🟡 Proof-of-concept (URL generation)

Chart Request
House System

Natural Language Astrology Conversations

Ask questions about Hellenistic astrology in plain English. Powered by Google Gemini AI with specialized knowledge of traditional techniques.

Features:

  • Explain techniques (dignities, profections, etc.)
  • Interpret placements
  • Answer questions with sources
  • Compare different methods
  • Educational, not predictive

Status: 🔑 Requires GOOGLE_API_KEY (free at makersuite.google.com)

Ask a Question

Example questions:
  • What are essential dignities?
  • How does sect work in Hellenistic astrology?
  • Explain annual profections step by step
  • What are Whole Sign houses?
  • Compare profections vs zodiacal releasing
 
## 🏗️ HERMES MCP Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    HERMES Application                       │
│                     (Gradio UI)                             │
└─────────────────────┬───────────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │   MCP Protocol Layer      │
        │   (Unified Interface)     │
        └─────────────┬─────────────┘
                      │
┌─────────────────────┼─────────────────────┬─────────────────┐
│                     │                     │                 │

┌───▼────┐ ┌────────▼────────┐ ┌─────▼──────┐ ┌────▼─────┐ │ Local │ │ Modal Serverless │ │ Astroseek │ │ Gemini │ │ MCP │ │ MCP │ │ MCP │ │ AI MCP │ └────────┘ └──────────────────┘ └────────────┘ └──────────┘ │ │ │ │ │ │ │ │ Fast & Scalable Cloud External Chart AI-Powered Reliable Calculations Integration Teaching ```

### Key Benefits:

1. **Modularity**: Each MCP server is independent
2. **Scalability**: Cloud functions handle heavy computation
3. **Resilience**: Automatic fallback if services unavailable
4. **Extensibility**: Easy to add new data sources
5. **Interoperability**: Standard protocol across all backends

### MCP Configuration

All servers configured in `.mcp_config.json`:

Try It Yourself

  1. Test each MCP server using the accordions above
  2. Compare performance between local and cloud
  3. See fallback behavior when services unavailable
  4. Check the code in hermes_local_mcp.py, astrodienst_mcp.py, gemini_mcp.py

For Hackathon Judges

HERMES demonstrates MCP's value by:

  • ✅ Integrating 5 different calculation backends
  • ✅ Showing graceful fallback (Modal → Local)
  • ✅ Connecting to external services (Astroseek, Astro.com)
  • ✅ Using AI for education (Gemini)
  • ✅ Maintaining consistent interface across all backends

This architecture makes ancient astrology accessible through modern protocols!