# Initial Idea: astro-mcp

## Topic
Building a new MCP server named **astro-mcp** that acts as an MCP client to the existing **ephemeris-mcp** service, consuming its `get_sky_state` tool and exposing calculated astrological data (naked chart calculations) via MCP tools for downstream interpretation by services like astro_service.

## Goal
- Provide a pure calculation layer that converts astronomical data from ephemeris-mcp into structured astrological data
- Calculate natal charts (planetary positions, houses, aspects), transit charts, and synastry charts
- Offer transit previews: given a person and a time range, list significant transit events (exact aspects, ingresses, stations)
- Maintain a lightweight database of persons with birth datetime, latitude, longitude, and optional nickname
- Output structured data (JSON-serializable) suitable for downstream astrological interpretation tools
- Do NOT provide interpretations - only calculations and raw data
- Follow the established MCP server manifest conventions (FastMCP + FastAPI, SSE transport, logging under ./logs/, health endpoint, etc.)
- Serve as a reusable data layer for astrological services and coding agents
- Provide a lightweight dashboard (Jinja2 + vanilla JS) for person management
- Consider optional SVG chart generation for visual representation (to be implemented in a later phase)

## Constraints & Context
- **Audience**: Downstream astrological services (like astro_service for horoscopes) and coding agents that need calculated astrological data for interpretation.
- **Manifest compliance**: Must adhere to `/home/lucky/.openclaw/workspace/MCP_SERVER_MANIFEST.md`:
  - Use FastMCP behind FastAPI.
  - Include `run.sh`, `killserver.sh`, `restart.sh`, `tests.sh`.
  - Mount SSE at `/mcp/sse` with `TransportSecuritySettings(enable_dns_rebinding_protection=False)`.
  - Provide minimal landing page (`GET /`) and liveness check (`GET /health`).
  - Keep `/health` lightweight.
  - Keep app‑specific code isolated from generic server plumbing.
  - Prefer non‑destructive schema changes (if any persistence is needed).
  - Store PID and logs under `./logs/`.
- **Data source**: The server will call `ephemeris-mcp:get_sky_state` (via MCP client) to get planetary positions for any given datetime/location, then perform astrological calculations (zodiac signs, houses, aspects, etc.) based on that data.
- **Language/runtime**: Python (use existing venv at `.venv`). Dependencies listed in `requirements.txt`.
- **Extensibility**: Design should allow adding more chart types (progressions, solar returns, etc.) and house systems without breaking changes.
- **Person database**: Simple SQLite table `persons` with columns: id, name, birth_datetime (UTC), latitude, longitude, elevation (optional), created_at.
- **Output format**: Structured data (dictionaries/lists) that can be JSON serialized - no interpretive text.
- **Interpretation boundary**: This server stops at calculation; interpretation happens in downstream services.
- **Astrological calculation standards** (based on industry practice):
  - Zodiac signs: 12 signs, 30° each
  - House systems: Support multiple systems (Placidus default, Koch, Equal House, etc.)
  - Aspects: Conjunction (0°), Sextile (60°), Square (90°), Trine (120°), Opposition (180°) with configurable orbs
  - Planets: Sun through Pluto, plus lunar nodes, Chiron (all available from ephemeris-mcp output)
  - Retrograde calculation: Based on apparent motion (speed_lon) from ephemeris-mcp data
  - Angles: Ascendant, Midheaven, Descendant, IC calculated from latitude, longitude, and sidereal time (from ephemeris-mcp)
- **Dashboard**: A simple Jinja2 + vanilla JS dashboard for person management (add, view, list persons) accessible at `/dashboard` or similar.
- **SVG Charts**: Optional feature to generate SVG visualizations of charts (natal, transit, synastry) for downstream services that wish to display them. This would be an additional tool/resource and is not required for the core calculation layer.

## Energy Preference
Practical, focused exploration – we want concrete calculation tool definitions and a clear implementation path for pure data provision.

## Ideas Collected

**[Tool #1] get_planetary_positions** (foundational)
_Concept:_ Wrapper around `ephemeris-mcp:get_sky_state` that returns the `planetary_positions.bodies` array with added zodiac sign and degree information (e.g., {"body": "sun", "sign": "Taurus", "degree": 12.5, ...}). Optionally filtered by a list of bodies. Includes retrograde flag based on speed_lon from ephemeris data.  
_Novelty:_ Provides astronomical data enhanced with astrological basics (signs, degrees, retrograde) as the base for all chart calculations.  
_Optional Parameters:_ `bodies` (list of strings) to filter which planets to return; defaults to all bodies.

**[Tool #2] calculate_natal_chart**
_Concept:_ Takes birth datetime, latitude, longitude, and optional house system (default Placidus) to calculate a complete natal chart structure including:
  - planets: array of objects with body, sign, degree, house, retrograde flag
  - houses: array of 12 house cusps (sign and degree)
  - aspects: array of objects (planet1, planet2, aspect_type, orb, applying/separating)
  - angles: ascendant, midheaven, descendant, ic (each with sign and degree)
  - chart_metadata: datetime, latitude, longitude, house_system  
_Novelty:_ Returns a complete, structured natal chart that downstream services can interpret for personality insights.  
_Optional Parameters:_ `house_system` (string, default "Placidus"); `orb_limits` (dict of aspect->max orb, defaults to standard orbs: conjunction 8°, sextile 6°, square 8°, trine 8°, opposition 8°).

**[Tool #3] calculate_transit_chart**
_Concept:_ Takes natal chart data (or birth data) and transit datetime to calculate:
  - transiting_planets: current planetary positions (same format as natal chart planets)
  - natal_to_transit_aspects: aspects between transiting planets and natal planets/angles
  - transit_to_natal_aspects: aspects between natal planets and transiting planets (same data, different perspective)
  - notable_periods: when slow planets make exact aspects (within 0°01' orb) to natal points
  - transiting_planets_in_houses: which natal house each transiting planet occupies  
_Novelty:_ Provides structured transit analysis data for timing events and understanding current influences.  
_Optional Parameters:_ `house_system` (default Placidus), `orb_limits` (same defaults as natal chart).

**[Tool #4] calculate_synastry_chart**
_Concept:_ Takes two sets of birth data (or two natal charts) to calculate relationship astrology structure including:
  - chart1_natal: first person's natal chart structure
  - chart2_natal: second person's natal chart structure
  - interaspects: aspects between chart1 planets and chart2 planets
  - house_overlays: for each person, where the other person's planets fall in their houses
  - composite_chart: midpoint method chart structure
  - davison_chart: davison relationship chart structure  
_Novelty:_ Provides structured relationship astrology data for downstream interpretation of interpersonal dynamics.  
_Optional Parameters:_ `house_system` (default Placidus for both charts), `orb_limits` (same defaults).

**[Tool #5] get_transit_preview**
_Concept:_ Given a person identifier (from the database) and a time range (start date, end date, or duration like "next 30 days"), returns a list of significant transit events within that period as structured data:
  - events: array of objects, each containing:
    - datetime: ISO timestamp of the event
    - event_type: "exact_aspect", "ingress", "retrograde_station_start", "retrograde_station_end", "lunar_phase_change"
    - description: machine-readable string (e.g., "transiting_jupiter_square_natal_mars")
    - planets_involved: array of body names
    - orb: exactness of the aspect (for aspect events)
    - additional_data: any relevant specifics (e.g., new moon phase)
  - time_range: requested start and end times  
_Novelty:_ Enables astrological services to quickly answer questions like "What transits are coming up for Lukas in the next month?" with structured data they can interpret.  
_Optional Parameters:_ `house_system` (default Placidus), `orb_limits` (default orbs), `event_types` (list of event types to include, defaults to all).

**[Tool #6] person_manage**
_Concept:_ CRUD-lite operations for the persons database:
  - add_person (name, birth_datetime, latitude, longitude, elevation optional, nickname)
  - get_person (by id or nickname)
  - list_persons (optional filter)
  - update_person / delete_person (if needed)  
_Novelty:_ Avoids requiring the agent to repeat birth data on every request; enables quick retrieval for transit previews and chart calculations.  
_Note:_ This tool set is complemented by a lightweight dashboard for manual person management.

**[Resource #1] chart_cache**
_Concept:_ A read-only MCP resource that provides access to recently calculated charts (with timestamps) to avoid recalculating the same chart multiple times in a session.  
_Novelty:_ Improves performance for services that need to reference the same chart multiple times.

**[Tool #7] set_default_location**
_Concept:_ (If we decide to allow mutable state) a tool that updates the server’s default latitude/longitude for subsequent chart calculations, stored in a tiny SQLite table.  
_Novelty:_ Avoids requiring the agent to repeat location coordinates on every request for charts from the same location.

**[Idea #8] generate_svg_chart** (optional, future feature)
_Concept:_ Given a chart structure (natal, transit, or synastry), generate an SVG visualization of the chart.
_Novelty:_ Provides a visual representation that can be embedded in web interfaces or reports.
_Note:_ This is an optional feature to be considered after the core calculation tools are stable. It would require an additional tool or resource and may depend on an SVG generation library.

## Next Steps (to be fleshed out in a later convergent phase)
1. Scaffold the project using the MCP Server Manifest (create dir, .gitignore, requirements.txt, README.md, PROJECT.md).
2. Implement the MCP client call to `ephemeris-mcp:get_sky_state` (likely via MCP SSE client or direct HTTP if exposed).
3. Create astrological calculation module (zodiac signs, houses, aspects) using the astronomical data from ephemeris-mcp.
4. Create SQLite schema for persons table and chart cache.
5. Define core tools: `get_planetary_positions`, `calculate_natal_chart`, `person_manage` (add/get/list).
6. Implement `get_transit_preview` using the person database and astrological calculation module.
7. Add `calculate_transit_chart` and `calculate_synastry_chart` as needed.
8. Add the health endpoint and landing page per manifest.
9. Add a lightweight dashboard (Jinja2 + vanilla JS) for person management.
10. Write `run.sh`/`killserver.sh` scripts and verify logging/pid handling.
11. Iteratively add more chart tools/resources based on priority.
12. Ensure all code is isolated in `src/astro_mcp/` with server wiring in `src/astro_mcp/server.py`.
13. Keep the MCP surface small and read‑only where possible (chart calculation tools are read-only; person DB is read/write but limited).
14. Document usage in README.md with example calls from coding agents/astro_service (e.g., "get transit preview for Lukas next month").
15. Add a test suite (`tests.sh`) that exercises each tool against mocked ephemeris-mcp data.
16. Consider house system options (Placidus, Koch, Equal House, etc.) and allow configuration.
17. (Optional, later phase) Consider implementing `generate_svg_chart` tool/resource for SVG chart visualization.

---
*End of initial idea capture. Ready to organize, prioritize, and plan actions.*