# 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