# Relationship Astrology — Astro MCP Feature Wishlist

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

## Already Supported (verify)

- [x] Natal chart calculation
- [x] Synastry chart (interchart aspects, house overlays)
- [x] Composite chart calculation
- [x] Person database
- [x] Aspect calculation with configurable orbs
- [x] House systems (Placidus, Equal, Whole Sign)
- [x] Transit chart calculation

## Needed for Relationship Interpretation

### 1. Davison Chart

| Feature | Description | Priority |
|---|---|---|
| **Davison chart calculation** | Calculate the midpoint-in-time-and-space chart for two people (average of birth dates, times, locations) | High |
| **Davison planet positions** | Return all planetary positions, signs, houses, angles for the Davison chart | High |
| **Davison aspects** | Calculate aspect patterns within the Davison chart | High |
| **Davison transits** | Calculate transits to the Davison chart (for timing relationship events) | Medium |
| **Davison progressions** | Calculate secondary progressions to the Davison chart | Low |

### 2. Synastry Enhancements

| Feature | Description | Priority |
|---|---|---|
| **Interchart aspects matrix** | Full matrix of aspects between all planets of Person A and Person B, with orbs | High |
| **House overlay report** | For each planet in Chart A, report which house it falls in Chart B (and vice versa) | High |
| **Top synastry aspects** | Return the 10-15 tightest/most significant interchart aspects, ranked by orb and significance | High |
| **Relationship significator aspects** | Specifically identify Venus-Mars, Moon-Venus, Sun-Moon, Sun-Saturn interchart aspects | High |
| **Saturn synastry aspects** | Specifically flag all Saturn interchart aspects to personal planets and nodes | High |
| **Node synastry aspects** | Specifically flag all interchart aspects to the nodal axes | High |

### 3. Composite Chart Enhanced Interpretation

| Feature | Description | Priority |
|---|---|---|
| **Composite planet meanings** | Return structured data for each composite planet (sign, house, aspects) | Medium |
| **Composite aspect list** | Return all aspects within the composite chart with orbs (tight orbs ≤3°) | Medium |
| **Composite angular planets** | Flag planets conjunct the composite angles (AC, MC, DC, IC) | Medium |
| **Composite chart ruler** | Identify and return the chart ruler's condition (sign, house, aspects) | Medium |
| **Composite unaspected planets** | Flag planets with no major aspects (relationship blind spots) | Medium |
| **Composite house emphasis** | Calculate which houses have the most planets (thematic emphasis) | Medium |
| **Composite transit report** | Calculate transits to composite chart planets/angles for timing | Medium |

### 4. Coalescent Chart (Nice-to-Have)

| Feature | Description | Priority |
|---|---|---|
| **Coalescent chart calculation** | Implement Lawrence Grinnell's harmonic coalescent method | Low |
| **Harmonic arc calculation** | Calculate shortest arcs between planet pairs and derive harmonic number | Low |
| **Coalescent transit sensitivity** | Identify transits that strongly activate the coalescent chart | Low |

### 5. Karmic Relationship Synthesis

| Feature | Description | Priority |
|---|---|---|
| **Karmic synastry summary** | Combine synastry + composite + Davison karmic indicators into a structured report | Medium |
| **Relationship type classifier** | Based on chart data, classify relationship type indicators (romantic, business, family, friendship, karmic) | Low |
| **Compatibility score** | Generate a structured compatibility assessment (not a single number, but category scores: emotional, sexual, intellectual, commitment, spiritual) | Low |

### 6. Relationship Timing

| Feature | Description | Priority |
|---|---|---|
| **Composite transit preview** | Transit-to-composite chart aspect snapshots over a date range | Medium |
| **Davison transit preview** | Transit-to-Davison chart aspect snapshots over a date range | Medium |
| **Synthesis transit preview** | Combine transit-to-natal (both people) + transit-to-composite/Davison for relationship timing | Low |
| **Eclipse activation of relationship charts** | Flag eclipses hitting composite/Davison angles or personal planets | Low |

## API Design Notes

### Davison Chart Input
```
person1_id: string (from database)
person2_id: string (from database)
  OR
person1_datetime, person1_latitude, person1_longitude
person2_datetime, person2_latitude, person2_longitude
house_system: "placidus" | "equal" | "whole_sign"
orb_limits: optional per-aspect-type orb configuration
```

### Synastry Enhancement Input
```
person1_id / person2_id (or raw birth data)
include_house_overlays: boolean
include_aspect_matrix: boolean
max_orb: number (default: 5)
significance_filter: optional minimum significance score
```

### Output Format
- Structured JSON with sections: `interchart_aspects`, `house_overlays`, `composite_planets`, `composite_aspects`, `davison_planets`, `davison_aspects`
- Each aspect: `{planet_a, planet_b, aspect_type, orb, applying/separating, significance}`
- Each house overlay: `{planet, owner_chart, house, house_meaning}`
- Summary fields: `top_aspects`, `saturn_contacts`, `node_contacts`, `venus_mars_contacts`

## Relationship Reading Workflow (for agents)

1. **Synastry** → interchart aspects + house overlays (interaction patterns, chemistry, friction)
2. **Composite chart** → the relationship's identity, structure, public face
3. **Davison chart** → the relationship's inner experience, emotional tone, long-term evolution
4. **Karmic overlay** → Saturn/Pluto/Node contacts across all three layers
5. **Transit timing** → transits to composite/Davison for relationship milestones
6. **Synthesis** → repeated themes across all layers = core relationship narrative