# Karmic Astrology — Astro MCP Feature Wishlist

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

## Already Supported (verify)

- [x] Natal chart calculation (all planets, houses, angles)
- [x] Lunar nodes (North/South) — sign, house, degree
- [x] Planetary positions with retrograde flags
- [x] Aspects between planets (conjunction, opposition, square, trine, sextile)
- [x] House systems (Placidus, Equal, Whole Sign)
- [x] Transit chart calculation
- [x] Synastry chart (interchart aspects, house overlays)
- [x] Composite chart calculation
- [x] Person database (store/retrieve birth data)

## Needed for Karmic Interpretation

### 1. Node-Related Computations

| Feature | Description | Priority |
|---|---|---|
| **Node sign/house lookup** | Return North & South Node sign, house, degree for any natal chart | High |
| **Node axis aspects** | Identify all aspects from natal planets to the nodal axis (conjunction, square, opposition, trine, sextile) with orbs | High |
| **Node conjunct planets** | Flag planets conjunct South Node (past-life gifts/blockages) and North Node (growth direction) | High |
| **Node square planets** | Flag planets square the nodal axis ("skipped steps" — unresolved past-life issues) | Medium |
| **Nodal axis by house** | Return which house the nodal axis falls in (life area of karmic focus) | High |

### 2. Saturn Karmic Computations

| Feature | Description | Priority |
|---|---|---|
| **Saturn sign/house** | Return Saturn's sign, house, degree, retrograde status | High |
| **Saturn aspects to personal planets** | Identify Saturn hard aspects (conjunction, square, opposition) to Sun, Moon, Venus, Mars | High |
| **Saturn retrograde flag** | Flag Saturn retrograde (unfinished past-life duties) | Medium |
| **Saturn-Node aspects** | Identify aspects between Saturn and the nodal axis (karmic contracts, blocks) | High |
| **Saturn return timing** | Calculate current/past/future Saturn return dates | Medium |

### 3. Pluto Evolutionary Computations

| Feature | Description | Priority |
|---|---|---|
| **Pluto sign/house** | Return Pluto's sign, house, degree | High |
| **Pluto polarity point** | Calculate the point opposite Pluto (PPP) — sign, house, degree | High |
| **Pluto-South Node conjunction** | Flag Pluto conjunct South Node (intense past-life pattern) | High |
| **Pluto aspects to nodes** | Identify all aspects from Pluto to the nodal axis | Medium |
| **Pluto aspects to personal planets** | Identify Pluto hard aspects to Sun, Moon, Venus, Mars | Medium |

### 4. Retrograde Planet Analysis

| Feature | Description | Priority |
|---|---|---|
| **Retrograde planet list** | Return all retrograde planets in a natal chart with their signs/houses | High |
| **Retrograde personal planets** | Flag retrograde Mercury, Venus, Mars (karmic communication/love/action themes) | Medium |
| **Retrograde outer planets** | Flag retrograde Jupiter, Saturn, Uranus, Neptune, Pluto | Low |

### 5. 12th House / Spiritual Karma

| Feature | Description | Priority |
|---|---|---|
| **12th house cusp sign** | Return the sign on the 12th house cusp | Medium |
| **12th house planets** | List any planets in the 12th house | Medium |
| **12th house ruler** | Identify the ruler of the 12th house and its sign/house/aspects | Low |

### 6. Karmic Synastry (Relationship Karma)

| Feature | Description | Priority |
|---|---|---|
| **Saturn-Node synastry** | Identify when one person's Saturn aspects the other's nodal axis | High |
| **Pluto-Node synastry** | Identify when one person's Pluto aspects the other's nodal axis | High |
| **Node conjunctions in synastry** | Flag when one person's planet conjuncts the other's North or South Node | High |
| **Saturn personal planet synastry** | Flag Saturn to Sun/Moon/Venus/Mars interchart aspects | High |
| **Karmic relationship summary** | Generate a summary of karmic indicators between two charts | Medium |

### 7. Composite Chart Karmic Features

| Feature | Description | Priority |
|---|---|---|
| **Composite Node axis** | Return composite chart nodal axis sign/house | Medium |
| **Composite Saturn** | Return composite Saturn sign, house, aspects | Medium |
| **Composite Pluto** | Return composite Pluto sign, house, aspects | Medium |

### 8. Transit Triggers for Karmic Periods

| Feature | Description | Priority |
|---|---|---|
| **Saturn transit to natal nodes** | Identify when transiting Saturn aspects the natal nodal axis | High |
| **Pluto transit to natal nodes** | Identify when transiting Pluto aspects the nodal axis | Medium |
| **Node return timing** | Calculate when the transiting nodal axis returns to natal position (~18.6 year cycle) | Medium |
| **Eclipse activation of nodes** | Flag eclipses conjunct the natal nodal axis | Low |

## Nice-to-Have

| Feature | Description |
|---|---|
| **Part of Fortune calculation** | Arabic Part of Fortune — sign, house, aspects |
| **Chiron position** | Chiron sign, house, aspects (wounded healer / deepest karmic wound) |
| **Vertex axis** | Vertex sign/house (fated encounters) |
| **Fixed star conjunctions** | Major fixed stars conjunct natal planets (karmic signatures) |
| **Planetary nodes** | Nodes of Pluto, Saturn, etc. (Jeffrey Wolf Green's evolutionary astrology) |
| **Karmic chart summary** | Auto-generated text summary of the main karmic themes in a natal chart |

## API Design Notes

- All features should accept a `person_id` from the database or raw birth data
- Orb configuration should be customizable (default: 5° for personal planets, 3° for outer)
- Return structured JSON with sign, house, degree, retrograde flag, aspect type, orb
- Support house system parameter (Placidus, Equal, Whole Sign)