Astro MCP Implementation Plan

Based on: WISHLIST_ANALYSIS.md Strategy: Expand existing tools rather than creating new ones where possible. Each phase is independently testable. Stop after each phase for review.

Phase 0: Fix Natal Chart Applying/Separating Bug

File: src/astro_mcp/tools.py, calculate_natal_chart function

The natal chart tool builds planet lines without speed_lon, then calls compute_aspects on bodies that also lack speed_lon. This means applying is always None for natal aspects.

Change: When building the aspect_bodies list in calculate_natal_chart, include speed_lon from the raw ephemeris data. This requires keeping a lookup of speed_lon by body name from the raw bodies.

# Before (line ~170):
aspect_bodies = [{"name": p["body"], "lon": p["absolute_lon"]} for p in planets]

# After:
speed_lookup = {b["body"]: b.get("speed_lon") for b in raw_bodies}
aspect_bodies = [{"name": p["body"], "lon": p["absolute_lon"], "speed_lon": speed_lookup.get(p["body"])} for p in planets]

Tests: Add a test in test_tools.py that verifies applying is not None for natal chart aspects when planets have different speeds.

Effort: ~5 lines changed.

Phase 1: Chart Overview Post-Processing Functions

File: src/astro_mcp/astrology.py (new functions)

Add these pure functions that operate on the planet list returned by calculate_natal_chart:

1.1 `get_element_balance(planets) -> dict`

Count planets by element. Each sign maps to an element:

Fire: Aries, Leo, Sagittarius
Earth: Taurus, Virgo, Capricornus
Air: Gemini, Libra, Aquarius
Water: Cancer, Scorpius, Pisces

Returns: {"fire": N, "earth": N, "air": N, "water": N, "percentages": {...}}

1.2 `get_modality_balance(planets) -> dict`

Count planets by modality:

Cardinal: Aries, Cancer, Libra, Capricornus
Fixed: Taurus, Leo, Scorpius, Aquarius
Mutable: Gemini, Virgo, Sagittarius, Pisces

Returns: {"cardinal": N, "fixed": N, "mutable": N, "percentages": {...}}

1.3 `get_hemisphere_emphasis(planets) -> dict`

Count planets by house ranges:

Upper (houses 7-12), Lower (1-6), East (10-3), West (4-9)

Returns: {"upper": N, "lower": N, "east": N, "west": N}

1.4 `detect_stelliums(planets) -> list`

Scan for 3+ planets in the same sign OR same house.

Returns: [{"type": "sign"|"house", "key": str, "planets": [str, ...]}, ...]

1.5 `get_empty_houses(planets) -> list[int]`

Return house numbers (1-12) with no planets.

1.6 `get_chart_ruler(ascendant_sign, planets) -> dict`

Sign-to-ruler mapping:

Aries -> Mars, Taurus -> Venus, Gemini -> Mercury, Cancer -> Moon,
Leo -> Sun, Virgo -> Mercury, Libra -> Venus, Scorpius -> Pluto (traditional: Mars),
Sagittarius -> Jupiter, Capricornus -> Saturn, Aquarius -> Uranus (traditional: Saturn),
Pisces -> Neptune (traditional: Jupiter)

Return the ruling planet's full data from the planets list.

1.7 `get_house_rulers(houses, planets) -> list`

For each house cusp sign, find the ruling planet and its condition.

1.8 `group_planets_by_house(planets) -> dict`

Returns: {house_number: [planet_names]}

1.9 `group_planets_by_sign(planets) -> dict`

Returns: {sign_name: [planet_names]}

1.10 `get_house_type_counts(planets) -> dict`

Angular (1,4,7,10), Succedent (2,5,8,11), Cadent (3,6,9,12).

1.11 `get_retrograde_planets(planets) -> list`

Filter planets where retrograde=True, return with sign + house.

1.12 `get_nodal_axis(planets, houses) -> dict`

Extract true_node from planets, compute South Node (opposite point).

1.13 `get_saturn_info(planets) -> dict`

Extract Saturn from planets list with sign, house, retrograde.

1.14 `get_part_of_fortune(ascendant_lon, sun_lon, moon_lon) -> dict`

Formula: normalize_degrees(ascendant_lon + moon_lon - sun_lon). Return sign + degree.

1.15 `get_pluto_polarity_point(pluto_lon) -> dict`

Formula: normalize_degrees(pluto_lon + 180). Return sign + degree.

Tests: Add all functions to test_astrology.py with known inputs.

Effort: ~200 lines in astrology.py, ~150 lines in test_astrology.py.

Phase 2: Aspect Pattern Detection

File: src/astro_mcp/astrology.py

2.1 `detect_aspect_patterns(planets, aspects) -> list`

Scan the aspect list for known patterns:

T-square: Find an opposition (A-B). Check if any planet C forms a square to both A and B. Apex = C.

Grand Trine: Find 3 planets where each pair is in trine (3 trines total). All 3 must be in the same element.

Grand Cross: Find 4 planets forming 2 oppositions and 4 squares (each planet opposes one and squares two others).

Yod: Find 2 planets in sextile. Check if any planet C forms a quincunx (150°) to both. Note: quincunx is not in the current aspect definitions -- add it first.

Add quincunx to ASPECT_DEFINITIONS:

{"name": "quincunx", "angle": 150.0, "default_orb": 3.0, "symbol": "Qx"}

Returns: [{"type": "T-square"|"Grand Trine"|"Grand Cross"|"Yod", "planets": [...], "apex": str|null, "modality": str|null, "element": str|null}]

Tests: Create synthetic planet configurations that form each pattern type and verify detection.

Effort: ~150 lines in astrology.py, ~100 lines in tests.

Phase 3: Chart Shape Detection

File: src/astro_mcp/astrology.py

3.1 `detect_chart_shape(planets) -> dict`

Analyze the angular distribution of planets to classify the chart shape:

Sort planets by longitude
Compute gaps between adjacent planets (including wraparound)
Find the largest gap
Classify:
- Bundle: All planets within 120° arc (largest gap >= 240°)
- Bowl: All planets within 180° arc (largest gap >= 180°)
- Bucket: All planets within 240° arc, with one planet opposite (singleton) -- largest gap < 240° but > 120°
- Splash: Planets distributed around the full 360° (largest gap < 120°)
- Locomotive: Planets within ~240° with a "locomotive" planet at the start of the empty arc
- Seesaw: Two clusters of planets roughly opposite each other
- Splay: Three or more planet pairs/groups distributed around the chart

Returns: {"shape": str, "largest_gap": float, "gap_start": float, "gap_end": float}

Tests: Create synthetic planet configurations for each shape.

Effort: ~80 lines in astrology.py, ~80 lines in tests.

Phase 4: Expand calculate_natal_chart with Overview

File: src/astro_mcp/tools.py

4.1 Add `include_overview` parameter to `calculate_natal_chart`

async def calculate_natal_chart(
    ...existing params...,
    include_overview: bool = False,
    include_patterns: bool = False,
    include_karmic: bool = False,
    top_n_aspects: int | None = None,
) -> dict[str, Any]:

When include_overview=True, add an "overview" key to the output containing:

element_balance, modality_balance, hemisphere_emphasis
stelliums, empty_houses
chart_ruler, house_rulers
planets_by_house, planets_by_sign
house_type_counts
retrograde_planets
lunar_phase (from ephemeris lunar_state)

When include_patterns=True, add an "aspect_patterns" key with T-square, Grand Trine, Grand Cross, Yod, and chart_shape.

When include_karmic=True, add a "karmic" key with:

nodal_axis, saturn_info, pluto_polarity_point
nodal_aspects (filter aspects for true_node)
saturn_aspects (filter aspects for Saturn hard aspects to personal planets)
retrograde_planets (emphasize personal planet retrogrades)
12th_house_analysis (cusp sign, planets, ruler)

When top_n_aspects is set, limit the aspects list to the N tightest.

Tests: Add tests in test_tools.py verifying each flag produces the expected output sections.

Effort: ~100 lines in tools.py, ~150 lines in tests.

Phase 5: Expand calculate_synastry_chart

File: src/astro_mcp/tools.py

5.1 Add parameters to `calculate_synastry_chart`

async def calculate_synastry_chart(
    ...existing params...,
    top_n_aspects: int | None = None,
    karmic_filter: bool = False,
    significator_filter: bool = False,
) -> dict[str, Any]:

top_n_aspects: Limit interaspects to top N by orb
karmic_filter: Only return interaspects involving Saturn, Pluto, or true_node
significator_filter: Only return interaspects involving Venus-Mars, Moon-Venus, Sun-Moon, Sun-Saturn pairs

Add a "summary" key to the output containing:

top_aspects: Top 10 interaspects by orb
saturn_contacts: All Saturn interchart aspects
node_contacts: All Node interchart aspects
venus_mars_contacts: All Venus-Mars interchart aspects
sun_moon_contacts: All Sun-Moon interchart aspects

Tests: Add tests verifying filters and summary sections.

Effort: ~60 lines in tools.py, ~100 lines in tests.

Phase 6: Full Davison Chart Tool

File: src/astro_mcp/tools.py

6.1 New tool: `calculate_davison_chart`

@mcp.tool()
async def calculate_davison_chart(
    person1_datetime: str,
    person1_latitude: float,
    person1_longitude: float,
    person2_datetime: str,
    person2_latitude: float,
    person2_longitude: float,
    elevation: float = 0.0,
    house_system: str = "placidus",
    orb_limits: dict[str, float] | None = None,
) -> dict[str, Any]:

Algorithm:

Compute Davison midpoint datetime (same as existing compute_davison_chart)
Compute Davison midpoint lat/lon (average of both birth locations)
Call call_sky_state at the Davison midpoint datetime + location
Calculate houses from the Davison LST + latitude
Build planet list with house placement
Calculate aspects between Davison planets
Calculate angles
Return full chart structure (same format as calculate_natal_chart)

6.2 New tool: `calculate_davison_chart_by_id`

Same as above but accepts person1_id and person2_id from the database.

6.3 Update `calculate_synastry_chart`

Change the Davison section from returning just midpoint coordinates to returning the full chart. Or alternatively, keep the midpoint data and add a "davison_chart_full" key.

Recommendation: Keep the existing midpoint data (for backward compatibility) and add a include_davison_full: bool = False parameter. When True, compute and include the full Davison chart.

Tests: Add tests for Davison chart calculation with known birth data.

Effort: ~150 lines in tools.py, ~100 lines in tests.

Phase 7: Transit Tools for Composite/Davison

File: src/astro_mcp/tools.py

7.1 New tool: `get_composite_transit_preview`

@mcp.tool()
async def get_composite_transit_preview(
    person1_datetime: str,
    person1_latitude: float,
    person1_longitude: float,
    person2_datetime: str,
    person2_latitude: float,
    person2_longitude: float,
    start_date: str,
    end_date: str,
    min_significance: float = 0.0,
) -> dict[str, Any]:

Algorithm:

Calculate composite chart (reuse calculate_composite_chart)
For each day in range, get transiting planet positions
Compute aspects between transiting planets and composite planet positions
Return daily snapshots (same format as get_transit_preview)

7.2 New tool: `get_davison_transit_preview`

Same pattern but using Davison chart positions as the "natal" targets.

7.3 `_byId` variants

Add get_composite_transit_preview_by_id and get_davison_transit_preview_by_id.

Tests: Add tests for composite and Davison transit previews.

Effort: ~150 lines in tools.py, ~100 lines in tests.

Phase 8: Return Type Updates

File: src/astro_mcp/tools.py

8.1 Update `_tool_names()`

Add all new tools to the _tool_names() function in server.py:

calculate_davison_chart
calculate_davison_chart_by_id
get_composite_transit_preview
get_composite_transit_preview_by_id
get_davison_transit_preview
get_davison_transit_preview_by_id

8.2 Update root endpoint test

Update test_root_lists_tools in test_server.py to include the new tool names.

Phase 9: Karmic Relationship Synthesis

File: src/astro_mcp/tools.py

9.1 New tool: `get_karmic_relationship_summary`

@mcp.tool()
async def get_karmic_relationship_summary(
    person1_id: str,
    person2_id: str,
    house_system: str = "placidus",
) -> dict[str, Any]:

Algorithm:

Get synastry chart (with karmic_filter=True)
Get composite chart
Get Davison chart
Extract karmic indicators:
- Saturn-Node contacts (synastry)
- Pluto-Node contacts (synastry)
- Node conjunctions (synastry)
- Saturn personal planet contacts (synastry)
- Composite Saturn/Pluto/Node positions
- Davison Saturn/Pluto/Node positions
Return structured summary with karmic weight assessment

Effort: ~100 lines in tools.py, ~50 lines in tests.

Phase 10: Nice-to-Have (Deferred)

These are lower priority and can be done after the above phases are complete:

Vertex axis (~25 lines in astrology.py)
Fixed star conjunctions (~100 lines + star catalog data)
Coalescent chart (~150 lines, complex algorithm)
Relationship type classifier (~80 lines, heuristic)
Compatibility scoring (~100 lines, heuristic)
Eclipse proximity (needs external eclipse data source)
Planetary nodes (needs specialized ephemeris data)

Summary of Changes

Phase	Files Changed	New Lines (approx)	New Tools
0: Bug fix	tools.py	~5	0
1: Post-processing	astrology.py, test_astrology.py	~350	0
2: Aspect patterns	astrology.py, test_astrology.py	~250	0
3: Chart shape	astrology.py, test_astrology.py	~160	0
4: Natal overview	tools.py, test_tools.py	~250	0 (params)
5: Synastry filters	tools.py, test_tools.py	~160	0 (params)
6: Davison chart	tools.py, test_tools.py, server.py	~250	2
7: Composite/Davison transits	tools.py, test_tools.py, server.py	~250	4
8: Return types	server.py, test_server.py	~20	0
9: Karmic synthesis	tools.py, test_tools.py	~150	1
Total		~1,845	7

Testing Strategy

All new astrology functions get unit tests in test_astrology.py
All new tool behaviors get integration tests in test_tools.py (with mocked ephemeris)
The existing 103 tests must continue to pass
Run pytest tests/ after each phase

Verification Checklist

After all phases:

pytest tests/ passes with no failures
All new functions have type annotations
All new tools appear in GET / output
All new tools have docstrings
No breaking changes to existing tool signatures (new params have defaults)

IMPLEMENTATION_PLAN.md 14 KB History Raw

Astro MCP Implementation Plan

Phase 0: Fix Natal Chart Applying/Separating Bug

Phase 1: Chart Overview Post-Processing Functions

1.1 get_element_balance(planets) -> dict

1.2 get_modality_balance(planets) -> dict

1.3 get_hemisphere_emphasis(planets) -> dict

1.4 detect_stelliums(planets) -> list

1.5 get_empty_houses(planets) -> list[int]

1.6 get_chart_ruler(ascendant_sign, planets) -> dict

1.7 get_house_rulers(houses, planets) -> list

1.8 group_planets_by_house(planets) -> dict

1.9 group_planets_by_sign(planets) -> dict

1.10 get_house_type_counts(planets) -> dict

1.11 get_retrograde_planets(planets) -> list

1.12 get_nodal_axis(planets, houses) -> dict

1.13 get_saturn_info(planets) -> dict

1.14 get_part_of_fortune(ascendant_lon, sun_lon, moon_lon) -> dict

1.15 get_pluto_polarity_point(pluto_lon) -> dict

Phase 2: Aspect Pattern Detection

2.1 detect_aspect_patterns(planets, aspects) -> list

Phase 3: Chart Shape Detection

3.1 detect_chart_shape(planets) -> dict

Phase 4: Expand calculate_natal_chart with Overview

4.1 Add include_overview parameter to calculate_natal_chart

Phase 5: Expand calculate_synastry_chart

5.1 Add parameters to calculate_synastry_chart

Phase 6: Full Davison Chart Tool

6.1 New tool: calculate_davison_chart

6.2 New tool: calculate_davison_chart_by_id

6.3 Update calculate_synastry_chart

Phase 7: Transit Tools for Composite/Davison

7.1 New tool: get_composite_transit_preview

7.2 New tool: get_davison_transit_preview

7.3 _byId variants

Phase 8: Return Type Updates

8.1 Update _tool_names()

8.2 Update root endpoint test

Phase 9: Karmic Relationship Synthesis

9.1 New tool: get_karmic_relationship_summary

Phase 10: Nice-to-Have (Deferred)

Summary of Changes

Testing Strategy

Verification Checklist

IMPLEMENTATION_PLAN.md 14 KB

History Raw

1.1 `get_element_balance(planets) -> dict`

1.2 `get_modality_balance(planets) -> dict`

1.3 `get_hemisphere_emphasis(planets) -> dict`

1.4 `detect_stelliums(planets) -> list`

1.5 `get_empty_houses(planets) -> list[int]`

1.6 `get_chart_ruler(ascendant_sign, planets) -> dict`

1.7 `get_house_rulers(houses, planets) -> list`

1.8 `group_planets_by_house(planets) -> dict`

1.9 `group_planets_by_sign(planets) -> dict`

1.10 `get_house_type_counts(planets) -> dict`

1.11 `get_retrograde_planets(planets) -> list`

1.12 `get_nodal_axis(planets, houses) -> dict`

1.13 `get_saturn_info(planets) -> dict`

1.14 `get_part_of_fortune(ascendant_lon, sun_lon, moon_lon) -> dict`

1.15 `get_pluto_polarity_point(pluto_lon) -> dict`

2.1 `detect_aspect_patterns(planets, aspects) -> list`

3.1 `detect_chart_shape(planets) -> dict`

4.1 Add `include_overview` parameter to `calculate_natal_chart`

5.1 Add parameters to `calculate_synastry_chart`

6.1 New tool: `calculate_davison_chart`

6.2 New tool: `calculate_davison_chart_by_id`

6.3 Update `calculate_synastry_chart`

7.1 New tool: `get_composite_transit_preview`

7.2 New tool: `get_davison_transit_preview`

7.3 `_byId` variants

8.1 Update `_tool_names()`

9.1 New tool: `get_karmic_relationship_summary`