# Modal Deployment Guide for HERMES MCP Server

## Overview

The HERMES MCP server provides serverless calculation tools for advanced Hellenistic astrology techniques. It's designed to run on Modal's serverless platform.

## Prerequisites

1. **Modal Account**
   - Sign up at https://modal.com
   - Free tier includes $30/month in credits
   - Sufficient for HERMES workload

2. **Modal Token**
   - Get your token from https://modal.com/settings/tokens
   - You'll need both `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`

## Installation

```bash
# Install Modal CLI
pip install modal

# Authenticate with Modal (one-time setup)
modal token new
# This will open a browser for authentication
```

## Deployment Steps

### 1. Set Up Modal Secrets (Optional)

If your MCP server needs to call external APIs:

```bash
modal secret create hermes-secrets \
  OPENAI_API_KEY=sk-... \
  ANTHROPIC_API_KEY=sk-ant-... \
  ELEVENLABS_API_KEY=...
```

### 2. Test Locally

```bash
# Run the MCP server locally to test
modal run mcp_server.py

# This will execute the main() function and test all tools
```

### 3. Deploy to Modal

```bash
# Deploy the MCP server to Modal's cloud
modal deploy mcp_server.py

# Output will show your deployment URL:
# https://your-workspace--hermes-astrology-mcp-function.modal.run
```

### 4. Get Your Function URLs

After deployment, Modal will provide URLs for each function:

```
https://[workspace]--hermes-astrology-mcp-calculate_full_dignities.modal.run
https://[workspace]--hermes-astrology-mcp-get_bound_ruler.modal.run
https://[workspace]--hermes-astrology-mcp-calculate_zodiacal_releasing.modal.run
```

## Available MCP Tools

The server exposes these calculation functions:

1. **calculate_full_dignities** - Complete essential dignity calculation
2. **get_bound_ruler** - Egyptian bounds (terms) lookup
3. **get_decan_ruler** - Decan (face) lookup
4. **calculate_zodiacal_releasing** - ZR period calculation
5. **calculate_firdaria** - Firdaria (Persian time-lord) periods
6. **find_fixed_stars** - Fixed star conjunctions

## Integration with HuggingFace Space

### Option 1: Direct Modal Calls (Current)

Add Modal credentials to HuggingFace Space secrets:
1. Go to https://huggingface.co/spaces/aamanlamba/hermes-astrology/settings
2. Add Repository Secrets:
   - `MODAL_TOKEN_ID`
   - `MODAL_TOKEN_SECRET`
3. Update `app.py` to call Modal functions when available

### Option 2: Embedded Functions (Current Implementation)

The current `app.py` includes all calculation functions directly.
This works well for HuggingFace Spaces and doesn't require Modal deployment.

**Recommendation:** Keep current embedded approach for Phase 2, deploy to Modal in Phase 3 for scalability.

## Testing Your Deployment

```python
# Test bound ruler function
import modal

app = modal.App.lookup("hermes-astrology-mcp")
get_bound_ruler = app.function_lookup("get_bound_ruler")

result = get_bound_ruler.remote("Aries", 8.5)
print(result)
# Should show: {"bound_ruler": "Venus", ...}
```

## Cost Estimation

Modal pricing (as of Nov 2024):
- CPU: $0.10 per hour
- Memory: $0.01 per GB-hour
- Requests: Free up to 1M/month

**Estimated costs for HERMES:**
- Average request: <0.1 seconds CPU time
- Memory: ~100MB per request
- Cost per 1000 requests: ~$0.001

With $30 free credits/month, you can handle ~30 million requests.

## Monitoring & Logs

View your deployment:
```bash
# Check app status
modal app list

# View logs
modal app logs hermes-astrology-mcp

# Check function statistics
modal app show hermes-astrology-mcp
```

## Troubleshooting

**Import errors:**
```bash
# Make sure all dependencies are in the Modal image
# Check mcp_server.py lines 15-19 for pip_install() list
```

**Authentication errors:**
```bash
# Re-authenticate
modal token new
```

**Function not found:**
```bash
# Redeploy
modal deploy mcp_server.py
```

## Next Steps

1. ✅ MCP server code is ready ([mcp_server.py](mcp_server.py))
2. ⏳ Install Modal CLI locally
3. ⏳ Authenticate with `modal token new`
4. ⏳ Test with `modal run mcp_server.py`
5. ⏳ Deploy with `modal deploy mcp_server.py`
6. ⏳ Add Modal credentials to HuggingFace secrets
7. ⏳ Update app.py to use Modal functions (Phase 3)

## Alternative: Keep Everything in Gradio (Current)

For the hackathon, the current implementation with all functions embedded in `app.py` works perfectly:
- ✅ No external dependencies
- ✅ Faster response times (no network calls)
- ✅ Simpler deployment
- ✅ Same functionality

**Modal deployment is optional** - it's more for production scale or if you want to showcase MCP architecture specifically.

---

**For this hackathon submission, you can skip Modal deployment** and note in your README that "MCP server is ready for Modal deployment (see MODAL_DEPLOYMENT.md)" as a future enhancement.