# Natal Astrology — Astro MCP Feature Wishlist

> What the astro MCP should compute/support to enable natal chart interpretation by agents.

## Already Supported (verify)

- [x] Natal chart calculation (all planets, houses, angles, aspects)
- [x] Planetary positions with sign, degree, retrograde flag
- [x] House systems (Placidus, Equal, Whole Sign)
- [x] Aspect calculation (conjunction, opposition, square, trine, sextile) with orbs
- [x] Person database (store/retrieve birth data)
- [x] Transit chart calculation
- [x] Transit preview (daily aspect snapshots with significance scoring)
- [x] Lunar nodes (North/South)
- [x] Synastry chart
- [x] Composite chart
- [x] Multiple birth data formats (ISO 8601 with timezone offset)

## Enhancements Needed for Natal Interpretation

### 1. Chart Overview / Summary

| Feature | Description | Priority |
|---|---|---|
| **Element balance report** | Count planets by element (fire/earth/air/water) with percentages | High |
| **Modality balance report** | Count planets by modality (cardinal/fixed/mutable) with percentages | High |
| **Hemisphere emphasis** | Report which hemisphere (upper/lower/east/west) has most planets | Medium |
| **Chart shape detection** | Identify bundle, bowl, bucket, splash, locomotive, seesaw, splay patterns | Medium |
| **Stellium detection** | Flag any sign or house with 3+ planets | High |
| **Empty house list** | Report which houses have no planets | Low |

### 2. Big Three Enhancement

| Feature | Description | Priority |
|---|---|---|
| **Chart ruler identification** | Return the planet ruling the Ascendant sign, with its sign/house/aspects | High |
| **Sun-Moon aspect** | Specifically return the aspect (if any) between Sun and Moon | Medium |
| **Sun/Moon phase** | Return the lunar phase at birth (new moon, waxing, full, waning) | Low |

### 3. Aspect Pattern Detection

| Feature | Description | Priority |
|---|---|---|
| **T-square detection** | Identify T-square patterns: two planets in opposition, both squaring a third planet | High |
| **Grand trine detection** | Identify grand trine patterns: three planets in trine, same element | High |
| **Grand cross detection** | Identify grand cross patterns: four planets forming two oppositions and four squares | High |
| **Yod detection** | Identify yod patterns: two sextile planets both quincunx a third | Medium |
| **Aspect pattern summary** | Return all major aspect patterns found in the chart with involved planets/houses | High |

### 4. Aspect Prioritization

| Feature | Description | Priority |
|---|---|---|
| **Top aspects by orb** | Return the N tightest aspects (smallest orbs) in the chart | High |
| **Aspects to Big Three** | Return all aspects involving Sun, Moon, or Ascendant | High |
| **Aspects to chart ruler** | Return all aspects involving the chart ruler | Medium |
| **Applying vs. separating** | Flag whether each aspect is applying or separating | Medium |

### 5. House Analysis

| Feature | Description | Priority |
|---|---|---|
| **House cusp signs** | Return the sign on each house cusp | High |
| **House rulers** | For each house, return the ruling planet and its sign/house/condition | Medium |
| **Planets in houses** | Group planets by house for quick house-themed reading | High |
| **Angular/succedent/cadent count** | Count planets by house type | Medium |

### 6. Sign Analysis

| Feature | Description | Priority |
|---|---|---|
| **Planets in signs** | Group planets by sign for quick sign-themed reading | High |
| **Sign dominance** | Identify which sign has the most planets (if any) | Low |

### 7. Retrograde Report

| Feature | Description | Priority |
|---|---|---|
| **Retrograde planet list** | Return all retrograde planets with sign/house | Medium |
| **Retrograde emphasis** | Flag charts with 3+ retrograde planets | Low |

### 8. Transit Integration for Natal Context

| Feature | Description | Priority |
|---|---|---|
| **Current transits to natal** | Return current transiting aspects to natal planets with orbs and applying/separating | High |
| **Upcoming major transits** | Return transits to natal Sun/Moon/Ascendant/chart ruler within next N days | Medium |
| **Saturn return flag** | Flag if the person is currently in their Saturn return window (~28-30 years) | Medium |
| **Jupiter return flag** | Flag if the person is currently in their Jupiter return window (~12 years) | Low |
| **Eclipse proximity** | Flag if any natal planet is within 5° of the current eclipse axis | Low |

### 9. Chart Synthesis Output (Nice-to-Have)

| Feature | Description | Priority |
|---|---|---|
| **Auto narrative summary** | Generate a structured text summary of the natal chart's main themes | Low |
| **Strength/challenge list** | Based on aspects, auto-generate a list of natural strengths and growth edges | Low |
| **Interpretation prompts** | Return structured prompts an agent can use to build a reading | Medium |

## API Design Notes

### Chart Overview Output
```json
{
  "element_balance": { "fire": 3, "earth": 2, "air": 4, "water": 3 },
  "modality_balance": { "cardinal": 4, "fixed": 5, "mutable": 3 },
  "hemisphere": { "upper": 7, "lower": 5, "east": 6, "west": 6 },
  "chart_shape": "bowl",
  "stelliums": [{"sign": "Scorpio", "planets": ["Sun", "Mercury", "Venus"]}],
  "empty_houses": [3, 9]
}
```

### Aspect Pattern Output
```json
{
  "patterns": [
    {
      "type": "T-square",
      "planets": ["Moon", "Mars", "Saturn"],
      "apex": "Saturn",
      "houses": [4, 7, 10],
      "signs": ["Cancer", "Libra", "Capricorn"],
      "modality": "cardinal"
    }
  ]
}
```

### Top Aspects Output
```json
{
  "top_aspects": [
    {
      "planet_a": "Sun",
      "planet_b": "Moon",
      "aspect": "trine",
      "orb": 2.3,
      "applying": true,
      "sign_a": "Leo",
      "sign_b": "Sagittarius",
      "house_a": 5,
      "house_b": 9
    }
  ]
}
```

## House System Notes

- Default: Placidus (most common in modern Western astrology)
- Support: Equal House, Whole Sign (important for Vedic/traditional work)
- All house-related features should respect the selected house system