astro-mcp/ORGANIZED_PLAN.md

Astro-MCP: Organized Themes and Action Plan

Theme 1: Foundation & Infrastructure

• Core Requirements: Follow MCP Server Manifest conventions (FastMCP + FastAPI, SSE transport, logging, health endpoint)
• Person Database: SQLite database for storing birth data (name, birth_datetime, lat/lon, nickname)
• Project Structure: Isolate app-specific code in src/astro_mcp/ with server wiring in src/astro_mcp/server.py
• Housekeeping Scripts: run.sh, killserver.sh, restart.sh, tests.sh
• Dashboard: Lightweight Jinja2 + vanilla JS dashboard for person management
• SVG Charts (Future): Optional SVG chart generation for visual representation

Theme 2: Astronomical Data Integration

• Primary Data Source: ephemeris-mcp:get_sky_state via MCP client
• Data Transformation: Convert astronomical output to astrological basics (zodiac signs, degrees, retrograde)
• Calculations: Zodiac signs (12 signs, 30° each), house systems, aspects, angles (ASC, MC, DSC, IC)
• Standards: Use data directly from ephemeris-mcp (no external ephemeris libraries needed)

Theme 3: Core Chart Calculation Tools (with Optional Parameters)

• Natal Chart Tool: Complete birth chart with planets in signs/houses, aspects, angles
  • Optional params: house_system (default Placidus), orb_limits (standard orbs)
• Transit Chart Tool: Current positions + aspects to natal chart
  • Optional params: house_system (default Placidus), orb_limits (standard orbs)
• Synastry Chart Tool: Relationship analysis (interaspects, house overlays, composite/davison charts)
  • Optional params: house_system (default Placidus), orb_limits (standard orbs)
• Chart Caching: Optional resource to avoid recalculating same charts

Theme 4: Transit & Timing Analysis

• Transit Preview: Given person + time range, return significant events (exact aspects, ingresses, stations)
• Event Types: Exact aspects (orb ≤ 0°01'), planet ingresses, retrograde stations, lunar phase changes
• Structured Output: Machine-readable descriptions for downstream interpretation
• Optional Parameters: house_system, orb_limits, event_types (filter which event types to include)

Theme 5: Person Management

• CRUD-lite Operations: Add, get, list persons (with optional update/delete)
• Birth Data Storage: UTC datetime, latitude, longitude, elevation, nickname
• Dashboard: Lightweight web interface for manual person management
• Efficiency: Avoid repeating birth data on every request

Theme 6: Configuration & Extensibility

• House Systems: Support multiple systems (Placidus default, Koch, Equal House, etc.)
• Aspect Configuration: Configurable orbs for different aspect types
• Chart Types: Design for adding progressions, solar returns, etc.
• Location Defaults: Optional tool to set default lat/lon for repeated calculations from same location

Theme 7: Manifest Compliance & Quality

• Health Endpoint: Lightweight /health for liveness checks
• Landing Page: Minimal GET / endpoint
• SSE Transport: Mount FastMCP at /mcp with SSE at /mcp/sse
• Security: Use TransportSecuritySettings(enable_dns_rebinding_protection=False)
• Logging/PID: Store under ./logs/ directory
• Testing: Comprehensive test suite via tests.sh

Action Plan

Phase 1: Project Setup & Foundation

1. Initialize project structure per MCP Server Manifest
2. Create .gitignore, requirements.txt, README.md, PROJECT.md
3. Set up src/astro_mcp/ directory with server.py
4. Implement basic FastAPI app with health and landing endpoints
5. Create dashboard template directory and basic Jinja2 template
6. Create run.sh, killserver.sh, restart.sh scripts
7. Initialize git repository and make initial commit

Phase 2: Data Layer & Person Management

1. Design SQLite schema for persons table
2. Implement person_manage tool (add_person, get_person, list_persons)
3. Create database initialization/connection handling
4. Test person CRUD operations
5. Create dashboard routes and templates for person management
6. Document API for person management

Phase 3: Astronomical Data Integration

1. Implement MCP client to call ephemeris-mcp:get_sky_state
2. Create get_planetary_positions tool wrapper
3. Add zodiac sign calculation (0-360° → sign + degree)
4. Add retrograde flag detection from speed_lon
5. Test with sample ephemeris-mcp output
6. Verify structured output format
7. Add optional bodies parameter to filter planets

Phase 4: Core Chart Calculations

1. Implement house system calculations (start with Placidus)
2. Calculate planetary house placements
3. Implement aspect detection (conjunction, sextile, square, trine, opposition)
4. Calculate orbs and applying/separating
5. Calculate angles (ASC, MC, DSC, IC) from lat/lon and sidereal time
6. Assemble complete natal chart structure
7. Add optional house_system parameter (default Placidus)
8. Add optional orb_limits parameter (standard defaults)
9. Test calculate_natal_chart tool with sample data

Phase 5: Transit & Relationship Charts

1. Implement calculate_transit_chart tool
2. Implement calculate_synastry_chart tool
3. Add optional parameters (house_system, orb_limits) to both
4. Verify chart caching mechanism (optional)
5. Test all chart tools with various inputs and parameter combinations

Phase 6: Transit Preview & Events

1. Implement transit preview algorithms (ingresses, retrograde stations, lunar phases)
2. Implement exact aspect detection within time ranges
3. Create get_transit_preview tool
4. Add optional parameters: house_system, orb_limits, event_types
5. Test with sample person data and date ranges

Phase 7: Integration & Compliance

1. Mount all tools as MCP tools via FastMCP
2. Ensure proper SSE transport at /mcp/sse
3. Verify health endpoint is lightweight
4. Test dashboard functionality and routes
5. Test housekeeping scripts (run/kill/restart)
6. Verify logging and PID file handling
7. Run full test suite via tests.sh

Phase 8: Documentation & Examples

1. Update README.md with usage examples
2. Document API for downstream services (like astro_service)
3. Provide example calls for transit previews ("What transits for Lukas next month?")
4. Document optional parameters for all tools
5. Document dashboard usage for person management
6. Document configuration options (house systems, etc.)
7. Finalize PROJECT.md with technical specifications

Phase 9: Optional Enhancements (Post-Core)

1. Consider implementing generate_svg_chart tool/resource for SVG chart visualization
2. Evaluate SVG generation libraries (svgwrite, etc.)
3. Implement SVG chart generation for natal, transit, and synastry charts
4. Add SVG chart as optional MCP resource or tool
5. Test SVG output with various chart types

Immediate Next Steps

1. Create project structure and initialize git repo
2. Implement basic server with health endpoint and dashboard routes
3. Add person management SQLite layer
4. Integrate with ephemeris-mcp:get_sky_state
5. Build get_planetary_positions tool with optional bodies parameter
6. Develop natal chart calculation with optional parameters