WISHLIST_ANALYSIS.md 23 KB
Astro MCP Wishlist Analysis
Generated: 2026-06-04 Analyzed against: src/astro_mcp/astrology.py, src/astro_mcp/tools.py, tests/
1. NATAL ASTROLOGY WISHLIST
1.1 Already Implemented (confirmed in code)
| Wishlist Item | Status | Location |
|---|---|---|
| Natal chart calculation (planets, houses, angles, aspects) | DONE | calculate_natal_chart in tools.py |
| Planetary positions with sign, degree, retrograde | DONE | get_planetary_positions, calculate_natal_chart |
| House systems (Placidus, Equal, Whole Sign) | DONE | calculate_houses in astrology.py |
| Aspect calculation (conj, opp, sq, tr, sx) with orbs | DONE | compute_aspects in astrology.py |
| Person database (store/retrieve birth data) | DONE | person_manage in tools.py |
| Transit chart calculation | DONE | calculate_transit_chart in tools.py |
| Transit preview (daily snapshots + significance) | DONE | get_transit_preview in tools.py |
| Lunar nodes (North/South) | DONE | true_node body from ephemeris |
| Synastry chart | DONE | calculate_synastry_chart in tools.py |
| Composite chart | DONE | calculate_composite_chart in tools.py |
| Multiple birth data formats (ISO 8601 with TZ) | DONE | All tools accept ISO 8601 |
| Applying/separating flag on aspects | PARTIAL | Computed in transit chart; natal chart does NOT pass speed_lon to compute_aspects |
1.2 Missing -- Easy Wins (post-processing of existing data)
1.2.1 Element Balance Report (High Priority)
- What: Count planets by element (fire/earth/air/water) with percentages
- Effort: Trivial -- bucket the 12 planets by sign element
- Where: New function
get_element_balance(planets)in astrology.py (~15 lines) - Integration: Add
include_overview: boolparam tocalculate_natal_chart, or new toolget_chart_overview
1.2.2 Modality Balance Report (High Priority)
- What: Count planets by modality (cardinal/fixed/mutable) with percentages
- Effort: Trivial -- bucket by sign modality
- Where: New function
get_modality_balance(planets)in astrology.py (~15 lines)
1.2.3 Hemisphere Emphasis (Medium Priority)
- What: Report which hemisphere (upper/lower/east/west) has most planets
- Effort: Trivial -- count planets by house ranges (upper=7-12, lower=1-6, etc.)
- Where: New function
get_hemisphere_emphasis(planets)in astrology.py (~15 lines)
1.2.4 Stellium Detection (High Priority)
- What: Flag any sign or house with 3+ planets
- Effort: Trivial -- scan planet list for sign/house clusters
- Where: New function
detect_stelliums(planets)in astrology.py (~20 lines)
1.2.5 Empty House List (Low Priority)
- What: Report which houses have no planets
- Effort: Trivial -- invert house placement list
- Where: New function
get_empty_houses(planets)in astrology.py (~10 lines)
1.2.6 Chart Ruler Identification (High Priority)
- What: Return the planet ruling the Ascendant sign, with its sign/house/aspects
- Effort: Trivial -- sign-to-ruler lookup table (Aries->Mars, Taurus->Venus, etc.), then find that planet in the list
- Where: New function
get_chart_ruler(angles, planets)in astrology.py (~15 lines)
1.2.7 Sun-Moon Aspect (Medium Priority)
- What: Specifically return the aspect (if any) between Sun and Moon
- Effort: Trivial -- filter existing aspect list for Sun-Moon pair
- Where: Filter on
calculate_natal_chartoutput, or paraminclude_big_three_aspects
1.2.8 Top Aspects by Orb (High Priority)
- What: Return the N tightest aspects (smallest orbs)
- Effort: Trivial -- aspects already sorted by orb; just add
top_nparameter - Where: Add
top_n: int | Noneparam tocalculate_natal_chart
1.2.9 Aspects to Big Three (High Priority)
- What: Return all aspects involving Sun, Moon, or Ascendant
- Effort: Trivial -- filter aspect list
- Where: Add
filter_to_big_three: boolparam or post-processing function
1.2.10 Aspects to Chart Ruler (Medium Priority)
- What: Return all aspects involving the chart ruler
- Effort: Trivial -- filter after identifying ruler
- Where: Same as above, chained
1.2.11 House Cusp Signs (High Priority)
- What: Return the sign on each house cusp
- Effort: Already returned in
housesarray (each house hassign,degree) - Status: Already done, just needs better documentation
1.2.12 House Rulers (Medium Priority)
- What: For each house, return the ruling planet and its sign/house/condition
- Effort: Trivial -- sign-to-ruler lookup + planet lookup
- Where: New function
get_house_rulers(houses, planets)in astrology.py (~25 lines)
1.2.13 Planets in Houses Grouping (High Priority)
- What: Group planets by house for quick house-themed reading
- Effort: Trivial -- each planet already has
housefield; just group - Where: New function
group_planets_by_house(planets)in astrology.py (~10 lines)
1.2.14 Planets in Signs Grouping (High Priority)
- What: Group planets by sign for quick sign-themed reading
- Effort: Trivial -- each planet already has
signfield; just group - Where: New function
group_planets_by_sign(planets)in astrology.py (~10 lines)
1.2.15 Angular/Succedent/Cadent Count (Medium Priority)
- What: Count planets by house type
- Effort: Trivial -- angular={1,4,7,10}, succedent={2,5,8,11}, cadent={3,6,9,12}
- Where: New function
get_house_type_counts(planets)in astrology.py (~15 lines)
1.2.16 Retrograde Planet List (Medium Priority)
- What: Return all retrograde planets with sign/house
- Effort: Trivial -- filter planet list where
retrograde=True - Where: New function
get_retrograde_planets(planets)in astrology.py (~10 lines)
1.2.17 Retrograde Emphasis Flag (Low Priority)
- What: Flag charts with 3+ retrograde planets
- Effort: Trivial -- count from retrograde list
1.2.18 Sun/Moon Phase (Low Priority)
- What: Return the lunar phase at birth
- Effort: Ephemeris already returns
lunar_state.phase_name; just expose it - Where: Add to
calculate_natal_chartoutput
1.2.19 Applying/Separation Fix for Natal Chart (Medium Priority)
- What: The natal chart tool does NOT pass
speed_lontocompute_aspects, soapplyingis alwaysNone - Effort: Small fix -- pass speed_lon through in the aspect computation loop
- Where:
calculate_natal_chartin tools.py, ~line 170
1.3 Missing -- New Algorithms Needed
1.3.1 Chart Shape Detection (Medium Priority)
- What: Identify bundle, bowl, bucket, splash, locomotive, seesaw, splay patterns
- Effort: Moderate -- analyze angular distribution of planets
- Algorithm: Compute the largest unoccupied arc; classify based on planet clustering
- Where: New function
detect_chart_shape(planets)in astrology.py (~80 lines)
1.3.2 Aspect Pattern Detection (High Priority)
- What: T-square, Grand Trine, Grand Cross, Yod detection
- Effort: Moderate -- graph topology analysis on aspect list
- Algorithm:
- T-square: find opposition pair, check if both square a common planet
- Grand trine: find 3 planets all in trine (same element)
- Grand cross: find 4 planets forming 2 oppositions + 4 squares
- Yod: find 2 sextile planets both quincunx a third
- Where: New function
detect_aspect_patterns(aspects)in astrology.py (~150 lines)
1.3.3 Saturn/Jupiter Return Flags (Medium Priority)
- What: Flag if person is currently in Saturn return (~28-30) or Jupiter return (~12 years)
- Effort: Moderate -- compute approximate return dates from birth date + orbital period, or scan transits
- Where: New function
get_return_dates(birth_datetime, planet)in astrology.py (~40 lines)
1.3.4 Eclipse Proximity (Low Priority)
- What: Flag if any natal planet is within 5° of current eclipse axis
- Effort: Needs eclipse data source not currently in ephemeris
- Status: Deferred -- requires external data
2. KARMIC ASTROLOGY WISHLIST
2.1 Already Implemented (confirmed)
| Wishlist Item | Status | Location |
|---|---|---|
| Natal chart calculation | DONE | calculate_natal_chart |
| Lunar nodes (North/South) | DONE | true_node in ephemeris |
| Planetary positions with retrograde | DONE | calculate_natal_chart |
| Aspects between planets | DONE | compute_aspects |
| House systems | DONE | calculate_houses |
| Transit chart | DONE | calculate_transit_chart |
| Synastry chart | DONE | calculate_synastry_chart |
| Composite chart | DONE | calculate_composite_chart |
| Person database | DONE | person_manage |
2.2 Missing -- Easy Wins (post-processing / filtering)
2.2.1 Node Sign/House Lookup (High Priority)
- What: Return North & South Node sign, house, degree
- Effort: Trivial --
true_nodeis already in planet list; South Node = opposite point - Where: New function
get_nodal_axis(planets, houses)in astrology.py (~10 lines)
2.2.2 Node Axis Aspects (High Priority)
- What: Identify all aspects from natal planets to the nodal axis
- Effort: Trivial -- filter existing aspects for
true_nodeinvolvement - Where: Filter on
calculate_natal_chartoutput, orinclude_nodal_aspectsparam
2.2.3 Node Conjunct Planets (High Priority)
- What: Flag planets conjunct South Node (past-life gifts) and North Node (growth)
- Effort: Trivial -- filter node axis aspects for conjunction
- Where: Post-processing of nodal aspects
2.2.4 Node Square Planets (Medium Priority)
- What: Flag planets square the nodal axis ("skipped steps")
- Effort: Trivial -- filter node axis aspects for square
2.2.5 Nodal Axis by House (High Priority)
- What: Return which house the nodal axis falls in
- Effort: Trivial --
true_nodealready hashousefield
2.2.6 Saturn Sign/House (High Priority)
- What: Return Saturn's sign, house, degree, retrograde status
- Effort: Trivial -- Saturn is already in planet list
- Where: New function
get_saturn_info(planets)in astrology.py (~10 lines)
2.2.7 Saturn Aspects to Personal Planets (High Priority)
- What: Identify Saturn hard aspects to Sun, Moon, Venus, Mars
- Effort: Trivial -- filter aspect list for Saturn + personal planet pairs with hard aspects
- Where: Filter on
calculate_natal_chartoutput
2.2.8 Saturn Retrograde Flag (Medium Priority)
- What: Flag Saturn retrograde
- Effort: Trivial -- check Saturn's
retrogradeflag
2.2.9 Saturn-Node Aspects (High Priority)
- What: Identify aspects between Saturn and the nodal axis
- Effort: Trivial -- filter aspect list for Saturn-true_node pairs
2.2.10 Retrograde Planet List (High Priority)
- What: Return all retrograde planets with signs/houses
- Effort: Same as natal wishlist item 1.2.16
2.2.11 12th House Cusp Sign (Medium Priority)
- What: Return the sign on the 12th house cusp
- Effort: Trivial --
houses[11]already has this
2.2.12 12th House Planets (Medium Priority)
- What: List any planets in the 12th house
- Effort: Trivial -- filter planets where
house == 12
2.2.13 12th House Ruler (Low Priority)
- What: Identify the ruler of the 12th house and its sign/house/aspects
- Effort: Trivial -- sign ruler lookup + planet lookup
2.2.14 Karmic Synastry Filters (High Priority)
- What: Saturn-Node, Pluto-Node, Node conjunctions in synastry
- Effort: Trivial -- filter existing interaspects for these pairs
- Where: Add
karmic_filter: boolparam tocalculate_synastry_chart
2.2.15 Composite Node/Saturn/Pluto (Medium Priority)
- What: Return composite chart nodal axis, Saturn, Pluto
- Effort: Trivial -- already in composite planet list; just surface prominently
2.2.16 Transit Triggers for Karmic Periods (High Priority)
- What: Saturn/Pluto transits to natal nodes
- Effort: Extend
get_transit_previewwithkarmic_only: boolfilter
2.3 Missing -- New Algorithms Needed
2.3.1 Pluto Polarity Point (PPP) (High Priority)
- What: Calculate the point opposite Pluto (sign, house, degree)
- Effort: Trivial --
normalize_degrees(pluto_lon + 180) - Where: New function
get_pluto_polarity_point(planets, houses)in astrology.py (~10 lines)
2.3.2 Saturn Return Timing (Medium Priority)
- What: Calculate current/past/future Saturn return dates
- Effort: Moderate -- Saturn orbital period ~29.5 years; compute from birth date
- Where: New function
get_saturn_return_dates(birth_datetime)in astrology.py (~30 lines)
2.3.3 Node Return Timing (Medium Priority)
- What: Calculate when transiting nodal axis returns to natal position (~18.6 year cycle)
- Effort: Moderate -- nodal period ~18.6 years
- Where: New function
get_node_return_dates(birth_datetime)in astrology.py (~20 lines)
2.4 Nice-to-Have (New Tools)
2.4.1 Part of Fortune (Low Priority)
- What: Arabic Part of Fortune -- sign, house, aspects
- Effort: Trivial -- formula: ASC + Moon - Sun (in degrees)
- Where: New function
get_part_of_fortune(angles, planets)in astrology.py (~10 lines)
2.4.2 Chiron Position (Low Priority)
- What: Chiron sign, house, aspects
- Effort: Trivial --
chironis already in the ephemeris mock data; confirm real ephemeris returns it - Status: Likely already available, needs verification
2.4.3 Vertex Axis (Low Priority)
- What: Vertex sign/house (fated encounters)
- Effort: Moderate -- Vertex = intersection of ecliptic with prime vertical, requires astronomical calculation
- Where: New function
calculate_vertex(lst, latitude)in astrology.py (~25 lines)
2.4.4 Fixed Star Conjunctions (Low Priority)
- What: Major fixed stars conjunct natal planets
- Effort: Moderate -- need fixed star catalog (Aldebaran, Regulus, Spica, Antares, etc.) + conjunction check
- Where: New data file + new function in astrology.py (~100 lines)
2.4.5 Planetary Nodes (Low Priority)
- What: Nodes of Pluto, Saturn, etc. (Jeffrey Wolf Green's evolutionary astrology)
- Effort: Complex -- requires specialized astronomical data not in standard ephemeris
- Status: Deferred
3. RELATIONSHIP ASTROLOGY WISHLIST
3.1 Already Implemented (confirmed)
| Wishlist Item | Status | Location |
|---|---|---|
| Natal chart calculation | DONE | calculate_natal_chart |
| Synastry chart (interchart aspects, house overlays) | DONE | calculate_synastry_chart |
| Composite chart calculation | DONE | calculate_composite_chart |
| Person database | DONE | person_manage |
| Aspect calculation with configurable orbs | DONE | compute_aspects |
| House systems | DONE | calculate_houses |
| Transit chart calculation | DONE | calculate_transit_chart |
3.2 Missing -- Easy Wins (post-processing / filtering)
3.2.1 Interchart Aspects Matrix (High Priority)
- What: Full matrix of aspects between all planets of Person A and Person B
- Effort: Already computed as
interaspectsincalculate_synastry_chart - Status: Done, just needs better surfacing
3.2.2 House Overlay Report (High Priority)
- What: For each planet in Chart A, report which house it falls in Chart B (and vice versa)
- Effort: Already computed as
house_overlaysincalculate_synastry_chart - Status: Done
3.2.3 Top Synastry Aspects (High Priority)
- What: Return the 10-15 tightest/most significant interchart aspects
- Effort: Trivial -- interaspects already sorted by orb; add
top_nparam
3.2.4 Relationship Significator Aspects (High Priority)
- What: Venus-Mars, Moon-Venus, Sun-Moon, Sun-Saturn interchart aspects
- Effort: Trivial -- filter interaspects for these planet pairs
- Where: Add
significator_filter: boolparam tocalculate_synastry_chart
3.2.5 Saturn Synastry Aspects (High Priority)
- What: Flag all Saturn interchart aspects to personal planets and nodes
- Effort: Trivial -- filter for Saturn as person1_planet or person2_planet
3.2.6 Node Synastry Aspects (High Priority)
- What: Flag all interchart aspects to the nodal axes
- Effort: Trivial -- filter for
true_nodeinvolvement
3.3 Missing -- New Tools Needed
3.3.1 Full Davison Chart Calculation (High Priority)
- What: Calculate the midpoint-in-time-and-space chart with full planetary positions, houses, angles, aspects
- Current state:
calculate_synastry_chartreturns Davison midpoint coordinates (date_jd, lat, lon) but does NOT compute planets, houses, or aspects for the Davison chart - Effort: Moderate -- compute sky state at Davison midpoint datetime + location, then calculate full chart
- Where: New tool
calculate_davison_chartin tools.py, reusingcalculate_natal_chartlogic (~150 lines)
3.3.2 Davison Transit Preview (Medium Priority)
- What: Transit-to-Davison chart aspect snapshots over a date range
- Effort: Moderate -- reuse
get_transit_previewwith Davison chart positions - Where: New tool
get_davison_transit_previewin tools.py (~80 lines)
3.3.3 Composite Transit Report (Medium Priority)
- What: Transits to composite chart planets/angles for timing
- Effort: Moderate -- reuse
get_transit_previewwith composite planet positions - Where: New tool
get_composite_transit_previewin tools.py (~80 lines)
3.3.4 Composite Enhanced Interpretation (Medium Priority)
- What: Composite planet meanings, angular planets, unaspected planets, house emphasis, chart ruler
- Effort: Moderate -- post-processing of existing composite chart data
- Where: New function
analyze_composite_chart(composite_data)in astrology.py (~100 lines)
3.3.5 Karmic Relationship Synthesis (Medium Priority)
- What: Combine synastry + composite + Davison karmic indicators into structured report
- Effort: Moderate -- aggregate filtering across all three chart types
- Where: New tool
get_karmic_relationship_summaryin tools.py (~100 lines)
3.4 Nice-to-Have (Complex / Low Priority)
3.4.1 Coalescent Chart (Low Priority)
- What: Lawrence Grinnell's harmonic coalescent method
- Effort: Complex -- compute harmonic numbers from planet pair arcs
- Where: New algorithm in astrology.py (~150 lines)
3.4.2 Relationship Type Classifier (Low Priority)
- What: Classify relationship type (romantic, business, family, friendship, karmic)
- Effort: Heuristic scoring based on aspect patterns
- Where: New function in astrology.py (~80 lines)
3.4.3 Compatibility Score (Low Priority)
- What: Category scores (emotional, sexual, intellectual, commitment, spiritual)
- Effort: Heuristic weighting of aspect types
- Where: New function in astrology.py (~100 lines)
3.4.4 Synthesis Transit Preview (Low Priority)
- What: Combine transit-to-natal (both people) + transit-to-composite/Davison
- Effort: Aggregation of existing transit data
- Where: New tool combining existing transit previews (~60 lines)
3.4.5 Eclipse Activation of Relationship Charts (Low Priority)
- What: Flag eclipses hitting composite/Davison angles or personal planets
- Effort: Needs eclipse data source
- Status: Deferred
4. CONSOLIDATED PRIORITY MATRIX
Tier 1: Post-Processing Only (Easiest -- add params to existing tools)
Pure filtering/bucketing of data already returned by existing tools.
| # | Feature | Wishlist(s) | Effort |
|---|---|---|---|
| 1 | Element/Modality/Hemisphere balance | Natal | ~45 lines |
| 2 | Stellium detection | Natal | ~20 lines |
| 3 | Chart ruler identification | Natal | ~15 lines |
| 4 | Top aspects by orb | Natal | param only |
| 5 | Aspects to Big Three / chart ruler | Natal | param only |
| 6 | House rulers | Natal | ~25 lines |
| 7 | Planets in houses/signs grouping | Natal | ~20 lines |
| 8 | Angular/succedent/cadent count | Natal | ~15 lines |
| 9 | Retrograde planet list | Natal, Karmic | ~10 lines |
| 10 | Node axis aspects | Karmic | param only |
| 11 | Saturn aspects to personal planets | Karmic | param only |
| 12 | Saturn-Node aspects | Karmic | param only |
| 13 | 12th house analysis | Karmic | ~15 lines |
| 14 | Top synastry aspects | Relationship | param only |
| 15 | Relationship significator aspects | Relationship | param only |
| 16 | Saturn/Node synastry filtering | Relationship | param only |
| 17 | Lunar phase at birth | Natal | expose existing |
| 18 | Applying/separating fix for natal | Natal | bug fix |
Tier 2: New Functions in astrology.py (Moderate -- pure math)
New algorithms that operate on existing data structures.
| # | Feature | Wishlist(s) | Effort |
|---|---|---|---|
| 19 | Chart shape detection | Natal | ~80 lines |
| 20 | Aspect pattern detection | Natal | ~150 lines |
| 21 | Pluto Polarity Point | Karmic | ~10 lines |
| 22 | Part of Fortune | Karmic | ~10 lines |
| 23 | Vertex axis | Karmic | ~25 lines |
| 24 | Saturn return dates | Natal, Karmic | ~30 lines |
| 25 | Node return dates | Karmic | ~20 lines |
| 26 | Composite enhanced analysis | Relationship | ~100 lines |
Tier 3: New MCP Tools (More involved -- require ephemeris calls)
New tools that make additional ephemeris calls.
| # | Feature | Wishlist(s) | Effort |
|---|---|---|---|
| 27 | Full Davison chart | Relationship | ~150 lines |
| 28 | Composite transit preview | Relationship | ~80 lines |
| 29 | Davison transit preview | Relationship | ~80 lines |
| 30 | Karmic relationship synthesis | Relationship, Karmic | ~100 lines |
Tier 4: Nice-to-Have (Complex or needs external data)
| # | Feature | Wishlist(s) | Effort |
|---|---|---|---|
| 31 | Coalescent chart | Relationship | ~150 lines |
| 32 | Fixed star conjunctions | Karmic | ~100 lines + data |
| 33 | Relationship type classifier | Relationship | ~80 lines |
| 34 | Compatibility scoring | Relationship | ~100 lines |
| 35 | Eclipse proximity/activation | Natal, Relationship | needs data source |
| 36 | Planetary nodes | Karmic | needs special data |
5. KEY ARCHITECTURAL RECOMMENDATIONS
5.1 Consolidate Post-Processing into a Chart Overview Tool
Rather than adding 15 boolean params to calculate_natal_chart, create a single new tool:
get_chart_overview(person_id_or_birth_data, include_karmic=false, include_patterns=false)
This tool would call calculate_natal_chart internally, then run all post-processing functions on the result. Keeps the base tool clean and provides a rich analysis layer on top.
5.2 Add Analysis Params to Synastry
Add optional params to calculate_synastry_chart:
top_n_aspects: int | None-- limit interaspects to top N by orbkarmic_filter: bool-- only return Saturn/Pluto/Node interaspectssignificator_filter: bool-- only return Venus-Mars, Moon-Venus, Sun-Moon, Sun-Saturn
5.3 Fix Natal Chart Applying/Separating
The natal chart tool should pass speed_lon to compute_aspects so the applying field is populated. This is a bug/omission, not a new feature.
5.4 Davison Chart is the Biggest Gap
The synastry tool returns Davison midpoint coordinates but not a full chart. A calculate_davison_chart tool is the highest-priority new tool -- it reuses existing ephemeris + astrology logic with the midpoint datetime/location.
5.5 Agent Guides Already Exist
The agent-guides/ directory already contains detailed interpretation guides for natal, karmic, and relationship astrology. These guides are consumed by agents, not by the MCP server. The MCP server's job is to provide the raw computational data; the guides tell agents how to interpret it. This analysis focuses on the computational layer only.